Rewrite fret diagrams portion of fretted-strings.itely

diff --git a/Documentation/user/fretted-strings.itely b/Documentation/user/fretted-strings.itely
index 6e736995a2744079e0a77f16b6550f6a8c60f09e..bdca9373130d10513ad9281c5b13a6902632b023 100644 (file)
--- a/Documentation/user/fretted-strings.itely
+++ b/Documentation/user/fretted-strings.itely
@@ -36,7 +36,8 @@ to fretted string instruments.
 * String number indications::   
 * Default tablatures::          
 * Custom tablatures::           
-* Fret diagrams::               
+* Automatic fret diagrams::               
+* Fret diagram markups::
 * Right-hand fingerings::       
 @end menu
 
@@ -329,10 +330,108 @@ Internals Reference:
 
 No guitar special effects have been implemented.
 
+@node Automatic fret diagrams
+@subsubsection Automatic fret diagrams
+@cindex fret diagrams
+@cindex chord diagrams
+
+Fret diagrams can be automatically created from entered notes using the 
+@code{FretBoards} context.  This context calculates strings and frets
+which can be used to play the notes.
+
+@lilypond[quote,ragged-right,verbatim]
+<<
+  \context ChordNames {
+     \chordmode { 
+       f1 g  
+     }
+  }
+  \context FretBoards {
+    < f, c f a c' f'>1
+    < g,\6 b, d g b g'>
+  }
+  \context Staff {
+    \clef "treble_8"
+    < f, c f a c' f'>1
+    < g, b, d g b' g'>
+  }  
+>>
+@end lilypond
+
+Notes can be explicitly placed on a string.  It is often enough
+to place only the lowest note on an explicit string; the rest of 
+the notes will then be placed appropriately by the @code{FretBoards}
+context.
+
+@lilypond[quote,ragged-right,verbatim]
+<<
+  \context ChordNames {
+     \chordmode { 
+       c1 c d:m d:m    
+     }
+  }
+  \context FretBoards {
+    < c e g c' e' > 1
+    < c\5 e g c' e' > 1
+    < d a d' f'>
+    < d\4 a d' f'>
+  }
+  \context Staff {
+    \clef "treble_8"
+    < c e g c' e' > 1
+    < c e g c' e' > 1
+    < d a d' f'>
+    < d a d' f'>
+  }  
+>>
+@end lilypond
+
+Fingerings can be added to FretBoard fret diagrams.
+
+@lilypond[quote, verbatim]
+<<
+  \context ChordNames {
+     \chordmode { 
+       c1 d:m          
+     }
+  }
+  \context FretBoards {
+    < c\5-3 e-2 g c'-1 e' > 1
+    < d\4 a-2 d'-3 f'-1>
+  }
+  \context Staff {
+    \clef "treble_8"
+    < c e g c' e' > 1
+    < d a d' f'>
+  }  
+>>
+@end lilypond
+
+The strings and frets for the @code{FretBoards} context depend
+on the @code{stringTunings} property, which has the same meaning
+as in the TabStaff context.  See @ref{Custom Tablatures} for 
+information on the @code{stringTunings} property. 
+
+The graphical layout of a fret diagram can be customized according to
+user preference through the properties of the @code{fret-diagram-interface}.
+Details are found at @rinternals{fret-diagram-interface}.  For a 
+@code{FretBoards} fret diagram, the interface properties belong to 
+@code{FretBoards}.
+
+@snippets
+The minimum fret to be used in calculating strings and frets for
+the FretBoard context can be set with the @code{minimumFret}
+property.
 
+@c TODO -- snippet showing minimum fret.
 
-@node Fret diagrams
-@subsubsection Fret diagrams
+@c TODO -- snippet for using StringTunings
+
+@seealso
+
+
+@node Fret diagram markups
+@subsubsection Fret diagram markups
 @cindex fret diagrams
 @cindex chord diagrams
 
@@ -344,6 +443,267 @@ produce equivalent markups, but have varying amounts of
 information in the markup string.  Details about the markup
 interfaces are found at @ref{Text markup commands}.
 
+The standard fret diagram markup string indicates the string
+number and the fret number for each dot to be placed on the string.
+In addition, open and unplayed (muted) strings can be indicated.
+
+@lilypond[quote, verbatim]
+<<
+  \context ChordNames {
+     \chordmode { 
+       c1 d:m          
+     }
+  }
+  \context Staff {
+    \clef "treble_8"
+    < c e g c' e' > 1 ^\markup 
+      \fret-diagram #"6-x;5-3;4-2;3-o;2-1;1-o;"
+    < d a d' f'> ^\markup
+      \fret-diagram #"6-x;5-x;4-o;3-2;2-3;1-1;"
+  }  
+>>
+@end lilypond
+
+Barre indications can be shown in the markup string.
+
+@lilypond[quote, verbatim]
+<<
+  \context ChordNames {
+     \chordmode {
+       f1 g
+     }
+  }
+  \context Staff {
+    \clef "treble_8"
+    < f, c f a c' f'>1 ^\markup
+      \fret-diagram #"c:6-1-1;6-1;5-3;4-3;3-2;2-1;1-1;"
+    < g, b, d g b' g'> ^\markup
+      \fret-diagram #"c:6-1-3;6-3;5-5;4-5;3-4;2-3;1-3;"
+  }
+>>
+@end lilypond
+
+The size of the fret diagram, and the number of frets in the diagram
+can be changed in the fret-diagram markup string.
+
+@lilypond[quote, verbatim]
+<<
+  \context ChordNames {
+     \chordmode {
+       f1 g
+     }
+  }
+  \context Staff {
+    \clef "treble_8"
+    < f, c f a c' f'>1 ^\markup
+      \fret-diagram #"s:1.5;c:6-1-1;6-1;5-3;4-3;3-2;2-1;1-1;"
+    < g, b, d g b' g'> ^\markup
+      \fret-diagram #"h:6;6-3;5-2;4-o;3-o;2-o;1-3;"
+  }
+>>
+@end lilypond
+
+The number of strings in a fret diagram can be changed to accomodate
+different instruments such as banjos and ukeleles with the fret-diagram
+markup string.
+
+@lilypond[quote, verbatim]
+<<
+  \context ChordNames {
+     \chordmode {
+       a1
+     }
+  }
+  \context Staff {
+        %% A chord for ukelele
+    a'1 ^\markup \fret-diagram #"w:4;4-2-2;3-1-1;2-o;1-o;"
+  }
+>>
+@end lilypond
+
+Fingering indications can be added, and the location of fingering labels
+can be controlled by the fret-diagram markup string.
+
+@lilypond[quote, verbatim]
+<<
+  \context ChordNames {
+     \chordmode { 
+       c1 d:m          
+     }
+  }
+  \context Staff {
+    \clef "treble_8"
+    < c e g c' e' > 1 ^\markup 
+      \fret-diagram #"f:1;6-x;5-3-3;4-2-2;3-o;2-1-1;1-o;"
+    < d a d' f'> ^\markup
+      \fret-diagram #"f:2;6-x;5-x;4-o;3-2-2;2-3-3;1-1-1;"
+  }  
+>>
+@end lilypond
+
+Dot radius and dot position can be controlled with the fret-diagram
+markup string.
+
+@lilypond[quote, verbatim]
+<<
+  \context ChordNames {
+     \chordmode { 
+       c1 d:m          
+     }
+  }
+  \context Staff {
+    \clef "treble_8"
+    < c e g c' e' > 1 ^\markup 
+      \fret-diagram #"d:0.3;6-x;5-3;4-2;3-o;2-1;1-o;"
+    < d a d' f'> ^\markup
+      \fret-diagram #"p:0.2;6-x;5-x;4-o;3-2;2-3;1-1;"
+  }  
+>>
+@end lilypond
+
+The fret-diagram-terse markup string omits string numbers; the string
+number is implied by the presence of semicolons.  There is one semicolon 
+for each string in the diagram.  The first semicolon corresponds to the
+highest string number and the last semicolon corresponds to the first string.
+Mute strings, open strings, and fret numbers can be indicated.
+
+@lilypond[quote, verbatim]
+<<
+  \context ChordNames {
+     \chordmode {
+       c1 d:m
+     }
+  }
+  \context Staff {
+    \clef "treble_8"
+    < c e g c' e' > 1 ^\markup
+      \fret-diagram-terse #"x;3;2;o;1;o;"
+    < d a d' f'> ^\markup
+      \fret-diagram-terse #"x;x;o;2;3;1;"
+  }
+>>
+@end lilypond
+
+Barre indicators can be included in the fret-diagram-terse markup string.
+
+@lilypond[quote, verbatim]
+<<
+  \context ChordNames {
+     \chordmode {
+       f1 g
+     }
+  }
+  \context Staff {
+    \clef "treble_8"
+    < f, c f a c' f'>1 ^\markup
+      \fret-diagram-terse #"1-(;3;3;2;1;1-);"
+    < g, b, d g b' g'> ^\markup
+      \fret-diagram-terse #"3-(;5;5;4;3;3-);"
+  }
+>>
+@end lilypond      
+
+Fingering indications can be included in the fret-diagram-terse markup string.
+
+@c Need to use override to enable fingerings to show this -- can we do so?
+@lilypond[quote, verbatim]
+<<    
+  \context ChordNames {
+     \chordmode {
+       c1 d:m
+     }
+  }
+  \context Staff {
+    \override Voice.TextScript 
+      #'fret-diagram-details #'finger-code = #'below-string
+    \clef "treble_8"
+    < c e g c' e' > 1 ^\markup
+      \fret-diagram-terse #"x;3-3;2-2;o;1-1;o;"
+    < d a d' f'> ^\markup
+      \fret-diagram-terse #"x;x;o;2-2;3-3;1-1;"
+  }
+>>
+@end lilypond
+
+Other fret diagram properties must be adjusted using @code{\override} when using
+the fret-diagram-terse markup.
+
+The fret-diagram-verbose markup string is in the format of a Scheme list.  Each
+element of the list indicates an item to be placed on the fret diagram.
+
+@lilypond[quote, verbatim]
+<<  \context ChordNames {
+     \chordmode {
+       c1 d:m
+     }
+  }
+  \context Staff {
+    \clef "treble_8"
+    < c e g c' e' > 1 ^\markup
+      \fret-diagram-verbose #'(
+        (mute 6)
+        (place-fret 5 3)
+        (place-fret 4 2)
+        (open 3)
+        (place-fret 2 1)
+        (open 1)
+      )
+    < d a d' f'> ^\markup
+      \fret-diagram-verbose #'(
+        (mute 6)
+        (mute 5)
+        (open 4)
+        (place-fret 3 2)
+        (place-fret 2 3)
+        (place-fret 1 1)
+      )
+  }
+>>
+@end lilypond
+
+Fingering indications and barres can be included in a 
+fret-diagram-verbose markup string.
+
+@c \override is necessary to make fingering visible
+@lilypond[quote, verbatim]
+<<
+  \context ChordNames {
+     \chordmode {
+       f1 g
+     }
+  }
+  \context Staff {
+    \clef "treble_8"
+    \override Voice.TextScript
+      #'fret-diagram-details #'finger-code = #'below-string
+
+    < f, c f a c' f'>1 ^\markup
+      \fret-diagram-verbose #'(
+        (place-fret 6 1)
+        (place-fret 5 3)
+        (place-fret 4 3)
+        (place-fret 3 2)
+        (place-fret 2 1)
+        (place-fret 1 1)
+        (barre 6 1 1)
+      )
+    < g, b, d g b' g'> ^\markup
+      \fret-diagram-verbose #'(
+        (place-fret 6 3 2)
+        (place-fret 5 2 1)
+        (open 4)
+        (open 3)
+        (open 2)
+        (place-fret 1 3 3)
+      )
+  }
+>>
+@end lilypond
+
+All other fret diagram properties must be adjusted using @code{\override} 
+when using the fret-diagram-verbose markup.
+
+@ignore
 The following example shows the three fret-diagram markup
 interfaces, along with examples of common tweaks.  For example,
 the size of the verbose fret diagram is reduced to 0.75, and the
@@ -377,17 +737,24 @@ and color of dots.
   c c c
 }
 @end lilypond
+@end ignore
 
-You can set a number of graphical properties according to your preference.
-Details about the property interface to fret diagrams are found at
-@rinternals{fret-diagram-interface}.
+The graphical layout of a fret diagram can be customized according to
+user preference through the properties of the @code{fret-diagram-interface}.
+Details are found at @rinternals{fret-diagram-interface}.  For a fret diagram
+markup , the interface properties belong to @code{Voice.TextScript}.
 
+@snippets
+@c TODO create snippets for changing properties.  Use regression test?
 
 @seealso
 
 Snippets:
 @rlsr{Fretted strings}.
 
+Internals Reference:
+@rinternals{fret-diagram-interface}.
+
 @node Right-hand fingerings
 @subsubsection Right-hand fingerings