X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Ffretted-strings.itely;h=eb071b4bd2f5f533946e66765dd144b4a68d0945;hb=5c14a087ca6cbd665fd631452b7b1283ba0387c3;hp=97a46662388fe45671428eaee6038d534aa9d6ae;hpb=dc5343d7467c78cc6983dadc53c0ea67f10e869f;p=lilypond.git

diff --git a/Documentation/user/fretted-strings.itely b/Documentation/user/fretted-strings.itely
index 97a4666238..eb071b4bd2 100644
--- a/Documentation/user/fretted-strings.itely
+++ b/Documentation/user/fretted-strings.itely
@@ -6,34 +6,57 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
-@c \version "2.11.51"
+@c \version "2.11.61"
 
 @node Fretted string instruments
 @section Fretted string instruments
 
+@lilypondfile[quote]{fretted-headword.ly}
+
+This section discusses several aspects of music notation that are unique
+to fretted string instruments.
+
 @cindex tablature
+@cindex tablature, guitar
+@cindex tablature, banjo
 @cindex guitar tablature
+@cindex banjo tablature
 
 @menu
-* Common notation for fretted strings::
-* Guitar::
-* Banjo::
+* Common notation for fretted strings::  
+* Guitar::                      
+* Banjo::                       
 @end menu
 
 @node Common notation for fretted strings
 @subsection Common notation for fretted strings
 
+This section discusses common notation that is unique
+to fretted string instruments.
+
 @menu
-* References for fretted strings::
-* String number indications::
-* Default tablatures::
-* Custom tablatures::
-* Fret diagrams::
-* Right hand fingerings::
+* References for fretted strings::  
+* String number indications::   
+* Default tablatures::          
+* Custom tablatures::           
+* Fret diagram markups::
+* Predefined fret diagrams::
+* Automatic fret diagrams::               
+* Right-hand fingerings::       
 @end menu
 
 @node References for fretted strings
-@subsubsection References for fretted strings
+@unnumberedsubsubsec References for fretted strings
+
+Music for fretted string instruments is normally notated on
+a single staff, either in traditional music notation or in
+tablature.  Sometimes the two types are combined, and it is
+especially common in popular music to use chord diagrams above
+a staff of traditional notation.  The guitar and the banjo are
+transposing instruments, sounding an octave lower than written. 
+Scores for these instruments should use the @code{"treble_8"} clef. 
+Some other elements pertinent to fretted string instruments 
+are covered elsewhere:
 
 @itemize
 @item Fingerings are indicated with @ref{Fingering instructions}.
@@ -50,18 +73,21 @@ in @ref{Collision resolution}.
 @seealso
 
 Notation Reference:
-@ref{Instrument names},
-@ref{Writing music in parallel},
 @ref{Fingering instructions},
 @ref{Ties},
+@ref{Collision resolution},
+@ref{Instrument names},
+@ref{Writing music in parallel},
 @ref{Arpeggio},
 @ref{List of articulations},
 @ref{Clef}.
 
 @node String number indications
-@subsubsection String number indications
+@unnumberedsubsubsec String number indications
 
-@cindex String numbers
+@cindex string numbers
+@cindex string vs. fingering numbers
+@cindex fingering vs. string numbers
 
 The string on which a note should be played may be indicated by
 appending @code{\@var{number}} to a note inside a chord construct
@@ -70,7 +96,8 @@ appending @code{\@var{number}} to a note inside a chord construct
 @warning{String numbers @strong{must} be defined inside a chord
 construct even if there is only a single note.}
 
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,quote,relative=0]
+\clef "treble_8"
 <c\5>4 <e\4> <g\3>2
 <c,\5 e\4 g\3>1
 @end lilypond
@@ -79,12 +106,14 @@ When fingerings and string indications are used together, their
 placement is controlled by the order in which the two items appear
 in the code:
 
-@lilypond[verbatim,quote,relative=2]
+@lilypond[verbatim,quote,relative=1]
+\clef "treble_8"
 <g\3-0>2
 <g-0\3>
 @end lilypond
 
 @snippets
+
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {controlling-the-placement-of-chord-fingerings.ly}
 
@@ -93,22 +122,25 @@ in the code:
 
 @seealso
 
-Snippets:
-@rlsr{Fretted strings}.
-
 Notation Reference:
 @ref{Fingering instructions}.
 
+Snippets:
+@rlsr{Fretted strings}.
+
 Internals Reference:
 @rinternals{StringNumber},
 @rinternals{Fingering}.
 
 
-
 @node Default tablatures
-@subsubsection Default tablatures
-@cindex Tablatures, basic
-@cindex Tablatures, default
+@unnumberedsubsubsec Default tablatures
+
+@cindex tablatures, basic
+@cindex tablatures, default
+
+@funindex TabStaff
+@funindex TabVoice
 
 Tablature notation is used for notating music for plucked string
 instruments.  Pitches are not denoted with note heads, but by
@@ -129,17 +161,20 @@ The notes are printed as tablature, by using @code{TabStaff} and
 @end lilypond
 
 @funindex minimumFret
+
 @cindex fret
 
 
-When no string is specified for a note, the note is assigned to the lowest string
-that can generate the note with a fret number greater than or equal to
-@code{minimumFret} is selected.  The default value for @code{minimumFret} is 0.
+When no string is specified for a note, the note is assigned to
+the lowest string that can generate the note with a fret number
+greater than or equal to the value of @code{minimumFret}.
+The default value for @code{minimumFret} is 0.
 
 
 @lilypond[quote,ragged-right,verbatim]
 \new StaffGroup <<
-   \new Staff \relative c' {
+   \new Staff \relative c {
+     \clef "treble_8"
      c16 d e f g4
      c,16 d e f g4
    }
@@ -151,46 +186,50 @@ that can generate the note with a fret number greater than or equal to
 >>
 @end lilypond
 
-@snippets
+@cindex harmonic indications in tablature notation
+@cindex tablature and harmonic indications
+@cindex slides in tablature notation
+@cindex tablature and slides
 
-The direction of stems is controlled the same way in tablature as
-in traditional notation. Beams can be made horizontal:
+Harmonic indications and slides can be added to tablature
+notation.
 
-@lilypond[quote,ragged-right,verbatim]
+@lilypond[fragment, verbatim, quote, relative=1]
 \new TabStaff {
-  \relative c {
-    g16 b d g
-    b d g b
-    \stemDown
-    \override Beam #'damping = #100000
-    g,,16 b d g
-    b d g b
+  \new TabVoice {
+    <c g'\harmonic> d\2\glissando e\2
   }
 }
 @end lilypond
 
+
+@snippets
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{stem-and-beam-behavior-in-tablature.ly}
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{polyphony-in-tablature.ly}
+
 @seealso
 
+Notation Reference:
+@ref{Stems}.
+
 Snippets:
 @rlsr{Fretted strings}.
 
-Notation Reference:
-@ref{Stems}
-
 Internals Reference: 
-@rinternals{TabNoteHead}, 
- 
-@rinternals{TabStaff},  
-
-@rinternals{TabVoice},  
-
+@rinternals{TabNoteHead},
+@rinternals{TabStaff},
+@rinternals{TabVoice},
 @rinternals{Beam}.
 
 @knownissues
 
 Chords are not handled in a special way, and hence the automatic
-string selector may easily select the same string for two notes in a
-chord.
+string selector may easily select the same string for two notes in
+a chord.
 
 In order to handle @code{\partcombine}, a @code{TabStaff} must use
 specially-created voices:
@@ -208,81 +247,416 @@ melodia = \partcombine { e4 g g g }{ e4 e e e }
 >>
 @end lilypond
 
+Guitar special effects are limited to harmonics and slides.
 
 @node Custom tablatures
-@subsubsection Custom tablatures
-@cindex Tablatures, custom
+@unnumberedsubsubsec Custom tablatures
 
-You can change the tuning of the strings.  A string tuning is given as
-a Scheme list with one integer number for each string, the number
-being the pitch (measured in semitones relative to middle C) of an
-open string.  The numbers specified for @code{stringTunings} are the
-numbers of semitones to subtract or add, starting the specified pitch
-by default middle C, in string order.  LilyPond automatically calculates
-the number of strings by looking at @code{stringTunings}.
+@cindex tablatures, custom
+@cindex tablature, banjo
+@cindex tablature, mandolin
+@cindex tablature, bass guitar
+@cindex tablature, predefined string tunings
+@cindex fretted instruments, predefined string tunings
+@cindex predefined string tunings for fretted instruments
 
-In the next example,
-@code{stringTunings} is set for the pitches e, a, d, and g
+@funindex StringTunings
 
-@lilypond[quote,ragged-right,fragment,verbatim]
-\new TabStaff <<
-  \set TabStaff.stringTunings = #'(-5 -10 -15 -20)
-  {
-    a,4 c' a e' e c' a e'
+LilyPond tabulature automatically calculates the fret for 
+a note based on the string to which the note is assigned.
+In order to do this, the tuning of the strings must be
+specified.  The tuning of the strings is given in the
+@code{StringTunings} property.
+
+LilyPond comes with predefined string tunings for banjo, mandolin,
+guitar and bass guitar.  Lilypond automatically sets the correct 
+transposition for predefined tunings.  The following example is
+for bass guitar, which sounds an octave lower than written.
+
+@lilypond[quote,ragged-right,verbatim]
+<<
+  \new Staff {
+    \clef "bass_8"
+    \relative c, {
+      c4 d e f
+    }
+  }
+  \new TabStaff {
+    \set TabStaff.stringTunings = #bass-tuning
+    \relative c, {
+      c4 d e f
+    }
   }
 >>
 @end lilypond
 
-LilyPond comes with predefined string tunings for banjo, mandolin, guitar
-and bass guitar.
-
-@example
-\set TabStaff.stringTunings = #bass-tuning
-@end example
+The default string tuning is @code{guitar-tuning}, which
+is the standard EADGBE tuning.  Some other predefined tunings are
+@code{guitar-open-g-tuning}, @code{mandolin-tuning} and
+@code{banjo-open-g-tuning}.  The predefined string tunings 
+are found in @code{scm/output-lib.scm}.
+
+A string tuning is a Scheme list of string pitches, 
+one for each string, ordered by string number from 1 to N,
+where string 1 is at the top of the tablature staff and
+string N is at the bottom.  This ordinarily results in ordering 
+from highest pitch to lowest pitch, but some instruments 
+(e.g. ukulele) do not have strings ordered by pitch.
+
+A string pitch in a string tuning list is the pitch difference  
+of the open string from middle C measured in semitones.  The 
+string pitch must be an integer.  Lilypond calculates the actual 
+pitch of the string by adding the string tuning pitch to the 
+actual pitch for middle C.
+
+LilyPond automatically calculates the number of strings in the
+@code{TabStaff} as the number of elements in @code{stringTunings}.
+
+Any desired string tuning can be created.  For example, we can
+define a string tuning for a four-string instrument with pitches
+of @code{a''},  @code{d''},  @code{g'}, and @code{c'}:
+
+
+@lilypond[quote,verbatim]
+mynotes = {
+    c'4 e' g' c'' |
+    e'' g'' b'' c'''
+}
 
-The default string tuning is @code{guitar-tuning} (the standard EADGBE
-tuning).
-Some other predefined tunings are @code{guitar-open-g-tuning},
-@code{mandolin-tuning} and @code{banjo-open-g-tuning}.
+<<
+  \new Staff {
+    \clef treble
+    \mynotes
+  }
+  \new TabStaff {
+    \set TabStaff.stringTunings = #'(21 14 7 0)
+    \mynotes
+  }
+>>
+@end lilypond
 
 @seealso
 
+Installed Files:
+@file{scm/output-lib.scm}.
+
 Snippets:
 @rlsr{Fretted strings}.
 
-The file @file{scm/@/output@/-lib@/.scm} contains the predefined string
-tunings.
-Internals Reference: @rinternals{Tab_note_heads_engraver}.
-
-@knownissues
-
-No guitar special effects have been implemented.
+Internals Reference: 
+@rinternals{Tab_note_heads_engraver}.
 
 
+@node Fret diagram markups
+@unnumberedsubsubsec Fret diagram markups
 
-@node Fret diagrams
-@subsubsection Fret diagrams
 @cindex fret diagrams
 @cindex chord diagrams
+@cindex diagrams, fret
+@cindex diagrams, chord for fretted instruments
+@cindex fret diagrams, custom
+@cindex custom fret diagrams
+
+Fret diagrams can be added to music as a markup to the desired
+note.  The markup contains information about the desired fret
+diagram.  There are three different fret-diagram markup
+interfaces: standard, terse, and verbose.  The three interfaces
+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
 
-Fret diagrams can be added to music as a markup to the desired note.  
-The markup contains information about the desired fret diagram.
-There are three different fret-diagram markup interfaces: standard, terse,
-and verbose.  The three interfaces 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}.
+@cindex barre indications
 
-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 finger indications are specified
-to appear below the diagram.  The terse diagram includes tweaks to 
-specify placement of finger code and color of dots.
+Barre indications can be added to the diagram from
+the fret-diagram markup string.
 
-@lilypond[verbatim, ragged-right, quote]
+@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, d g b d' g'> ^\markup
+      \fret-diagram #"c:6-1-3;6-3;5-5;4-5;3-4;2-3;1-3;"
+  }
+>>
+@end lilypond
+
+@cindex fret-diagram markup
+
+@funindex fret-diagram
+@funindex \fret-diagram
+
+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.35;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
+
+@cindex fret-diagram-terse markup
+
+@funindex fret-diagram-terse
+@funindex \fret-diagram-terse
+
+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, d g b d' 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.
+
+@cindex fret-diagram-verbose markup
+
+@funindex fret-diagram-verbose
+@funindex \fret-diagram-verbose
+
+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
+finger indications are specified to appear below the diagram.  The
+terse diagram includes tweaks to specify placement of finger code
+and color of dots.
+
+@lilypond[verbatim,ragged-right,quote]
 \new Voice {
-  d'^\markup \fret-diagram #"6-x;5-x;4-o;3-2;2-3;1-2;"
-  d' d' d'
-  fis'^\markup \override #'(size . 0.75) {
+  \clef "treble_8"
+  d^\markup \fret-diagram #"6-x;5-x;4-o;3-2;2-3;1-2;"
+  d d d
+  fis^\markup \override #'(size . 0.75) {
     \override #'(finger-code . below-string) {
       \fret-diagram-verbose #'((place-fret 6 2 1) (barre 6 1 2)
                                (place-fret 5 4 3) 
@@ -292,103 +666,512 @@ specify placement of finger code and color of dots.
                                (place-fret 1 2 1))
     }
   }
-  fis' fis' fis'
-  c'^\markup \override #'(dot-radius . 0.35) {
+  fis fis fis
+  c^\markup \override #'(dot-radius . 0.35) {
     \override #'(finger-code . in-dot) {
       \override #'(dot-color . white) {
         \fret-diagram-terse #"x;3-1-(;5-2;5-3;5-4;3-1-);"
       }
     }
   }
-  c' c' c'
+  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}.
+@cindex customized fret diagram
+@cindex fret diagram, customized
+@cindex diagram, fret, customized
+
+@funindex 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
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{customizing-markup-fret-diagrams.ly}
 
 
 @seealso
 
+Notation Reference:
+@ref{Text markup commands}.
+
 Snippets:
 @rlsr{Fretted strings}.
 
-@node Right hand fingerings
-@subsubsection Right hand fingerings
+Internals Reference:
+@rinternals{fret-diagram-interface}.
 
-Right-hand fingerings @var{p-i-m-a} can be entered using 
-@code{<@var{note}-\rightHandFinger @var{finger} >}.
-The right-hand fingering indication must occur within a @code{<>} chord 
-construct for it to be printed in the score, even if it is a single note.  
-There must be a hyphen after the note and a space before the closing @code{>}.
+@node Predefined fret diagrams
+@unnumberedsubsubsec Predefined fret diagrams
 
 
-@lilypond[quote,ragged-right,fragment,verbatim]
-\relative c' {
-  <c-\rightHandFinger #1 >4 
-  <e-\rightHandFinger #2 > 
-  <g-\rightHandFinger #3 > 
-  <c-\rightHandFinger #4 >
-  <c,-\rightHandFinger #1 e-\rightHandFinger #2 g-\rightHandFinger #3 c-\rightHandFinger #4 >1
+@cindex fret diagrams
+@cindex chord diagrams
+
+@funindex FretBoards
+@funindex stringTunings
+
+Fret diagrams can be displayed using the @code{FretBoards} context.  By
+default, the @code{FretBoards} context will display fret diagrams that
+are stored in a lookup table:
+
+@lilypond[verbatim, ragged-right, quote]
+\include "predefined-guitar-fretboards.ly"
+\context FretBoards {
+  \chordmode {
+    c1 d
+  }
 }
 @end lilypond
 
-For convenience, you can abbreviate @code{\rightHandFinger} to something
-short, for example @code{RH},
+The default predefined fret diagrams are contained in the file
+@code{predefined-guitar-fretboards.ly}.  Fret diagrams are 
+stored based on the pitches of a chord and the value of
+@code{stringTunings} that is currently in use.  
+@code{predefined-guitar-fretboards.ly} contains predefined 
+fret diagrams only for @code{guitar-tuning}.  Predefined fret
+diagrams can be added for other instruments or other tunings
+by following the examples found in 
+@code{predefined-guitar-fretboards.ly}.  
+
+Chord pitches can be entered
+either as simultaneous music or using chord mode (see
+@ref{Chord mode overview}).
+
+@lilypond[verbatim, ragged-right,quote]
+\include "predefined-guitar-fretboards.ly"
+\context FretBoards {
+  \chordmode {c1}
+  <c' e' g'>1
+}
+@end lilypond
 
-@example
-#(define RH rightHandFinger)
-@end example
+@cindex chord names with fret diagrams
+@cindex fret diagrams with chord names
 
-@cindex fingerings, right hand, for guitar
-@cindex right hand fingerings for guitar
+@funindex ChordNames
+@funindex chordmode
+@funindex \chordmode
 
-@snippets
+It is common that both chord names and fret diagrams are displayed together.
+This is achieved by putting a @code{ChordNames} context in parallel with
+a @code{FretBoards} context and giving both contexts the same music.
 
-You may exercise greater control over the placement of right-hand 
-fingerings by setting @code{strokeFingerOrientations},
+@lilypond[verbatim, ragged-right, quote]
+\include "predefined-guitar-fretboards.ly"
+mychords = \chordmode{
+  c1 f g
+}
 
-@lilypond[quote,verbatim,ragged-right,fragment,relative=1]
-#(define RH rightHandFinger)
-{
-  \set strokeFingerOrientations = #'(up down)
-  <c-\RH #1 es-\RH #2 g-\RH #4 > 4
-  \set strokeFingerOrientations = #'(up right down)
-  <c-\RH #1 es-\RH #2 g-\RH #4 > 4
+<<
+  \context ChordNames {
+    \mychords
+  }
+  \context FretBoards {
+    \mychords
+  }
+>>
+@end lilypond
+
+@cindex transposing fret diagrams
+@cindex fret diagrams, transposing
+@cindex diagrams, fret, transposing
+
+Predefined fret diagrams are transposable, as long as a diagram for the
+transposed chord is stored in the fret diagram table.
+
+@lilypond[verbatim, ragged-right, quote]
+\include "predefined-guitar-fretboards.ly"
+mychords = \chordmode{
+  c1 f g
+}
+
+mychordlist = {
+  \mychords
+  \transpose c e { \mychords}
 }
+<<
+  \context ChordNames {
+    \mychordlist
+  }
+  \context FretBoards {
+    \mychordlist
+  }
+>>
 @end lilypond
 
-The letters used for the fingerings are contained in the property
-@code{digit-names}, but they can also be set individually by supplying
-@code{\rightHandFinger} with a string argument, as in the following example
 
+The predefined fret diagram table contains seven chords (major, minor,
+augmented, diminished, dominant seventh, major seventh, minor seventh)
+for each of 17 keys.  A complete list of the predefined fret diagrams is
+shown in @ref{Predefined fretboard diagrams}.  If there is no entry in
+the table for a chord, the FretBoards engraver will calculate a
+fret-diagram using the automatic fret diagram functionality described in
+@ref{Automatic fret diagrams}.
 
-@lilypond[quote,verbatim,ragged-right,fragment,relative=1]
-#(define RH rightHandFinger)
-{
-  \set strokeFingerOrientations = #'(right)
-  \override StrokeFinger #'digit-names = ##("x" "y" "z" "!" "@")
-  <c-\RH #5 >4
-  <c-\RH "@">4
-  <c-\RH #2 >4
-  <c-\RH "z">4
+@lilypond[verbatim, ragged-right, quote]
+\include "predefined-guitar-fretboards.ly"
+mychords = \chordmode{
+  c1 c:9
 }
+
+<<
+  \context ChordNames {
+    \mychords
+  }
+  \context FretBoards {
+    \mychords
+  }
+>>
 @end lilypond
 
-This example combines left-hand fingering, string indication, and 
-right-hand fingering
+@cindex fret diagrams, adding custom
+@cindex custom fret diagrams, adding
+@cindex adding custom fret diagrams
 
-@lilypond[quote,ragged-right,fragment,verbatim]
-#(define RH rightHandFinger)
-\relative c' {
-  <c-3\5-\RH #1 >4 
-  <e-2\4-\RH #2 > 
-  <g-0\3-\RH #3 > 
-  <c-1\2-\RH #4 >
+Fret diagrams can be added to the fret diagram table.  To add a diagram,
+you must specify the chord for the diagram, the tuning to be used, and the
+fret-diagram-terse definition string for the diagram.
+
+@lilypond[verbatim, ragged-right, quote]
+\include "predefined-guitar-fretboards.ly"
+
+\storePredefinedDiagram \chordmode {c:9} 
+                        #guitar-tuning
+                        #"x;3-2;2-1;3-3;3-4;x;"
+
+mychords = \chordmode{
+  c1 c:9
 }
+
+<<
+  \context ChordNames {
+    \mychords
+  }
+  \context FretBoards {
+    \mychords
+  }
+>>
+@end lilypond
+
+Different fret diagrams for the same chord name can be stored using different
+octaves of pitches.
+
+@lilypond[verbatim, ragged-right, quote]
+\include "predefined-guitar-fretboards.ly"
+
+\storePredefinedDiagram \chordmode {c'} 
+                        #guitar-tuning
+                        #(offset-fret 2 (chord-shape 'bes))
+
+mychords = \chordmode{
+  c1 c'
+}
+
+<<
+  \context ChordNames {
+    \mychords
+  }
+  \context FretBoards {
+    \mychords
+  }
+>>
 @end lilypond
 
+@cindex fretted instruments, chord shapes
+@cindex chord shapes for fretted instruments
+
+@funindex \addChordShape
+@funindex add ChordShape
+@funindex storePredefinedDiagram
+@funindex \storePredefinedDiagram
+
+In addition to fret diagrams, LilyPond stores an internal list of chord
+shapes.  The chord shapes are fret diagrams that can be shifted along
+the neck to different posistions to provide different chords.  Chord
+shapes can be added to the internal list and then used to define
+predefined fret diagrams.
+
+@lilypond[verbatim, ragged-right, quote]
+\include "predefined-guitar-fretboards.ly"
+
+% add a new chord shape
+
+\addChordShape #'powerf #"1-1;3-3;3-4;x;x;x;"
+
+% add some new chords based on the power chord shape
+
+\storePredefinedDiagram \chordmode {f'} 
+                        #guitar-tuning 
+                        #(chord-shape 'powerf)
+\storePredefinedDiagram \chordmode {g'} 
+                        #guitar-tuning
+                        #(offset-fret 2 (chord-shape 'powerf))
+
+mychords = \chordmode{
+  f1 f' g g' 
+}
+
+<<
+  \context ChordNames {
+    \mychords
+  }
+  \context FretBoards {
+    \mychords
+  }
+>>
+@end lilypond
+
+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 
+predefined fret diagram, the interface properties belong to 
+@code{FretBoards.FretBoard}.
+
+@snippets
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{customizing-fretboard-fret-diagrams.ly}
+
+
+@seealso
+
+Notation Reference:
+@ref{Custom tablatures},
+@ref{Automatic fret diagrams},
+@ref{Chord mode overview},
+@ref{Predefined fretboard diagrams}.
+
+Installed Files:
+@file{ly/predefined-guitar-fretboards.ly}.
+
+Snippets:
+@rlsr{Fretted strings}.
+
+Internals Reference:
+@rinternals {fret-diagram-interface}.
+
+
+@node Automatic fret diagrams
+@unnumberedsubsubsec Automatic fret diagrams
+
+@cindex fret diagrams, automatic
+@cindex chord diagrams, automatic
+@cindex automatic fret diagrams
+@cindex automatic chord diagrams
+
+Fret diagrams can be automatically created from entered notes using the 
+@code{FretBoards} context.  If no predefined diagram is available for
+the entered notes in the active @code{stringTunings}, this context
+calculates strings and frets that 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
+
+@funindex predefinedFretboardsOff
+@funindex \predefinedFretboardsOff
+@funindex predefinedFretboardsOn
+@funindex \predefinedFretboardsOn
+
+As no predefined diagrams are loaded by default, automatic calculation 
+of fret diagrams is the default behavior.  Once default diagrams are
+loaded, automatic calculation can be enabled and disabled with predefined
+commands:
+
+@lilypond[quote,ragged-right,verbatim]
+
+\storePredefinedDiagram <c e g c' e'>
+                        #guitar-tuning
+                        #"x;3-1-(;5-2;5-3;5-4;3-1-1);"
+<<
+  \context ChordNames {
+     \chordmode { 
+       c1 c c 
+     }
+  }
+  \context FretBoards {
+    <c e g c' e'>1
+    \predefinedFretboardsOff
+    <c e g c' e'>
+    \predefinedFretboardsOn
+    <c e g c' e'>
+  }
+  \context Staff {
+    \clef "treble_8"
+    <c e g c' e'>1
+    <c e g c' e'>
+    <c e g c' e'>
+  }  
+>>
+@end lilypond
+
+  
+
+Sometimes the fretboard calculator will be unable to find
+an accceptable diagram.  This can often be remedied by
+manually assigning a note to a string.  In many cases, only one
+note need be manually placed on a 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 
+     }
+  }
+  \context FretBoards {
+    < c g c' e' g'> 1
+    < c g\4 c' e' g'> 1
+  }
+  \context Staff {
+    \clef "treble_8"
+    < c g c' e' g'> 1
+    < c g c' e' g'> 1
+  }  
+>>
+@end lilypond
+
+@cindex fret diagrams, adding fingerings
+@cindex fingerings, adding to fret diagrams
+
+Fingerings can be added to FretBoard fret diagrams.
+
+@lilypond[quote, verbatim]
+<<
+  \context ChordNames {
+     \chordmode { 
+       c1 d:m          
+     }
+  }
+  \context FretBoards {
+    < c-3 e-2 g c'-1 e' > 1
+    < d a-2 d'-3 f'-1>
+  }
+  \context Staff {
+    \clef "treble_8"
+    < c e g c' e' > 1
+    < d a d' f'>
+  }  
+>>
+@end lilypond
+
+The minimum fret to be used in calculating strings and frets for
+the FretBoard context can be set with the @code{minimumFret}
+property.
+
+@lilypond[quote, verbatim]
+<<
+  \context ChordNames {
+     \chordmode {
+       d1:m d:m
+     }
+  }
+  \context FretBoards {
+    < d a d' f'>
+    \set FretBoards.minimumFret = #5
+    < d a d' f'>
+  }
+  \context Staff {
+    \clef "treble_8"
+    < d a d' f'>
+    < 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.FretBoard}.
+
+@predefined
+@code{\predefinedFretboardsOff},
+@code{\predefinedFretboardsOn}.
+
+@seealso
+
+Notation Reference:
+@ref{Custom tablatures}.
+
+Snippets:
+@rlsr{Fretted strings}.
+
+Internals Reference:
+@rinternals {fret-diagram-interface}.
+
+
+@node Right-hand fingerings
+@unnumberedsubsubsec Right-hand fingerings
+
+@cindex fretted instruments, right hand fingerings
+@cindex fingerings, right hand for fretted instruments
+@cindex right hand fingerings for fretted instruments
+
+@funindex rightHandFinger
+@funindex \rightHandFinger
+
+Right-hand fingerings @var{p-i-m-a} must be entered within a  
+chord construct @code{<>} for them to be printed in the score, 
+even when applied to a single note. 
+
+@warning{There @strong{must} be a hyphen after the note and a space 
+before the closing @code{>}.}
+
+@lilypond[quote,verbatim,relative=0]
+\clef "treble_8"
+<c-\rightHandFinger #1 >4 
+<e-\rightHandFinger #2 > 
+<g-\rightHandFinger #3 > 
+<c-\rightHandFinger #4 >
+<c,-\rightHandFinger #1 e-\rightHandFinger #2 g-\rightHandFinger #3 c-\rightHandFinger #4 >1
+@end lilypond
+
+For convenience, you can abbreviate @code{\rightHandFinger} to something
+short, for example @code{RH},
+
+@example
+#(define RH rightHandFinger)
+@end example
+
+
+@snippets
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{placement-of-right-hand-fingerings.ly}
+
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{fingerings,-string-indications,-and-right-hand-fingerings.ly}
+
 @seealso
 
 Snippets:
@@ -401,65 +1184,97 @@ Internals Reference:
 @node Guitar
 @subsection Guitar
 
-@c TODO Make a snippet based on
-@c http://www.nabble.com/Creating-a-nice-formatted-Chords-%2B-Lyrics-layout-for-guitar-players-to13829430.html
-@c and include it somewhere -td
+Most of the notational issues associated with guitar music are
+covered sufficiently in the general fretted strings section, but there
+are a few more worth covering here.  Occasionally users want to 
+create songbook-type documents having only lyrics with chord
+indications above them.  Since Lilypond is a music typesetter,
+it is not recommended for documents that have no music notation
+in them.  A better alternative is a word processor, text editor, 
+or, for experienced users, a typesetter like GuitarTeX.
 
 @menu
-* Guitar tablatures::
-* Indicating position and barring::
+* Indicating position and barring::  
+* Indicating harmonics and dampened notes::  
 @end menu
 
-@node Guitar tablatures
-@subsubsection Guitar tablatures
-
-@c TODO Add text
-TBC
-
 @node Indicating position and barring
-@subsubsection Indicating position and barring
+@unnumberedsubsubsec Indicating position and barring
+
+@cindex indicating position and barring for fretted instruments
+@cindex fretted instruments, indicating position and barring
 
 This example demonstrates how to include guitar position and
 barring indications.
 
 @lilypond[quote,ragged-right,fragment,verbatim,relative=0]
-\clef "G_8"
-b16 d16 g16 b16 e16
+\clef "treble_8"
+b16 d g b e
 \textSpannerDown
 \override TextSpanner #'bound-details #'left #'text = #"XII "
   g16\startTextSpan
-  b16 e16 g16 e16 b16 g16\stopTextSpan
-e16 b16 g16 d16
+  b16 e g e b g\stopTextSpan
+e16 b g d
 @end lilypond
 
+@seealso
+
+Notation Reference:
+@ref{Text spanners}.
+
+Snippets:
+@rlsr{Fretted strings},
+@rlsr{Expressive marks}.
+
+@node Indicating harmonics and dampened notes
+@unnumberedsubsubsec Indicating harmonics and dampened notes
 
-Stopped (X) note heads are used in guitar music to signal a place where the
-guitarist must play a certain note or chord, with its fingers just
-touching the strings instead of fully pressing them.  This gives the sound a
-percussive noise-like sound that still maintains part of the original
-pitch.  It is notated with cross note heads; this is
-demonstrated in @ref{Special note heads}.
+@cindex fretted instruments, dampened notes
+@cindex fretted instruments, harmonics
+@cindex dampened notes on fretted instruments
+@cindex harmonics on fretted instruments
+
+Special note heads can be used to indicate dampened notes or 
+harmonics.  Harmonics are normally further explained with a 
+text markup.
+
+@lilypond[quote,ragged-right,fragment,verbatim]
+\relative c' {
+  \clef "treble_8"
+  \override Staff.NoteHead #'style = #'cross
+  g8 a b c b4
+  \override Staff.NoteHead #'style = #'harmonic-mixed
+  d^\markup { \italic { \fontsize #-2 { "harm. 12" }}} <g b>1
+}
+@end lilypond
 
 @seealso
 
 Snippets:
 @rlsr{Fretted strings}.
 
+Notation Reference:
+@ref{Special note heads},
+@ref{Note head styles}.
+
 @node Banjo
 @subsection Banjo
 
-@menu Banjo tablatures
-* Banjo tablatures::
+@menu
+* Banjo tablatures::            
 @end menu
 
 @node Banjo tablatures
-@subsubsection Banjo tablatures
-@cindex Banjo tablatures
+@unnumberedsubsubsec Banjo tablatures
+
+@cindex banjo tablatures
+@cindex tablature, banjo
+
+LilyPond has basic support for the five-string banjo.  When making tablatures
+for five-string banjo, use the banjo tablature format function to get
+correct fret numbers for the fifth string:
 
-LilyPond has basic support for five stringed banjo.  When making tablatures
-for five stringed banjo, use the banjo tablature format function to get
-correct
-fret numbers for the fifth string:
+@c due to crazy intervals of banjo music, absolute pitch is recommended
 
 @lilypond[quote,ragged-right,fragment,verbatim]
 \new TabStaff <<
@@ -474,12 +1289,21 @@ fret numbers for the fifth string:
 >>
 @end lilypond
 
+@cindex banjo tunings
+@cindex tunings, banjo
+
+@funindex banjo-c-tuning
+@funindex banjo-modal-tuning
+@funindex banjo-open-d-tuning
+@funindex banjo-open-dm-tuning
+@funindex four-string-banjo
+
 A number of common tunings for banjo are predefined in LilyPond:
 @code{banjo-c-tuning} (gCGBD), @code{banjo-modal-tuning} (gDGCD),
 @code{banjo-open-d-tuning} (aDF#AD) and @code{banjo-open-dm-tuning}
 (aDFAD).
 
-These tunings may be converted to four string banjo tunings using the
+These tunings may be converted to four-string banjo tunings using the
 @code{four-string-banjo} function:
 
 @example
@@ -494,3 +1318,6 @@ Snippets:
 The file @file{scm/@/output@/-lib@/.scm} contains predefined banjo tunings.
 
 
+
+
+