X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Ffretted-strings.itely;h=b6afe1b5814ffff7b2377cfc5f12711a4c064ccd;hb=a46782b6db53f55c0ce494f5ca001e187b81e4e1;hp=98de6e3335d68fcd4fc66d0c8d9dd68b32d81830;hpb=3c00bd3295cf8542f610a4975b5e11d26cf6e009;p=lilypond.git

diff --git a/Documentation/notation/fretted-strings.itely b/Documentation/notation/fretted-strings.itely
index 98de6e3335..b6afe1b581 100644
--- a/Documentation/notation/fretted-strings.itely
+++ b/Documentation/notation/fretted-strings.itely
@@ -7,7 +7,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.13.46"
+@c \version "2.17.6"
 
 @node Fretted string instruments
 @section Fretted string instruments
@@ -76,7 +76,6 @@ in @ref{Collision resolution}.
 
 @end itemize
 
-
 @seealso
 Notation Reference:
 @ref{Fingering instructions},
@@ -98,37 +97,36 @@ Notation Reference:
 @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
-@code{<>}.
-
-@warning{String numbers @strong{must} be defined inside a chord
-construct even if there is only a single note.}
+appending @code{\@var{number}} to a note.
 
 @lilypond[verbatim,quote,relative=0]
 \clef "treble_8"
-<c\5>4 <e\4> <g\3>2
+c4\5 e\4 g2\3
 <c,\5 e\4 g\3>1
 @end lilypond
 
 When fingerings and string indications are used together, their
-placement is controlled by the order in which the two items appear
-in the code:
+placement can be controlled by the order in which the two items appear
+in the code @emph{only} if they appear inside of an explicit chord:
+applied to whole chords or single notes @emph{outside} of chords,
+fingerings are placed using a different mechanism.
 
 @lilypond[verbatim,quote,relative=1]
 \clef "treble_8"
-<g\3-0>2
+g4\3-0
+g-0\3
+<g\3-0>
 <g-0\3>
 @end lilypond
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {controlling-the-placement-of-chord-fingerings.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {allowing-fingerings-to-be-printed-inside-the-staff.ly}
 
-
 @seealso
 Notation Reference:
 @ref{Fingering instructions}.
@@ -223,19 +221,23 @@ symbols = {
 @cindex fret
 
 @funindex minimumFret
+@funindex restrainOpenStrings
 
 By default pitches are assigned to the lowest playing position on the
 fret-board (first position).  Open strings are automatically preferred.
-If you would like a certain pitch to be played on a specific string
-you can add a string number indication to the pitch name.  If you
-define pitch names and string numbers without a chord construct
-(@code{<>}) the string number indications do not appear in traditional
-notation.  It is much more comfortable to define the playing position
-by using the value of @code{minimumFret}.  The default value for
-minimumFret is 0.
+If you would like a certain pitch to be played on a specific string you
+can add a string number indication to the pitch name.  If you don't want
+to have string number indications appear in traditional notation, you
+can override the respective stencil.  Usually it will be more
+comfortable to define the playing position by using the value of
+@code{minimumFret}.  The default value for minimumFret is 0.
 
+Even when @code{minimumFret} is set, open strings are used whenever
+possible.  This behaviour can be changed by setting @code{restrainOpenStrings}
+to @code{#t}.
 
 @lilypond[quote,ragged-right,verbatim]
+\layout { \override Voice.StringNumber.stencil = ##f }
 \new StaffGroup <<
    \new Staff \relative c {
      \clef "treble_8"
@@ -248,39 +250,44 @@ minimumFret is 0.
      c16 d e f g4
      c,16\5 d\5 e\4 f\4 g4\4
      \set TabStaff.minimumFret = #5
+     \set TabStaff.restrainOpenStrings = ##t
      c,16 d e f g4
    }
 >>
 @end lilypond
 
-@funindex \tabChordRepetition
+@funindex \tabChordRepeats
+@funindex \chordRepeats
+@cindex Chord, repetition
+@cindex repetition, using @code{q}
 
 Chord constructs can be repeated by the chord repetition symbol
-@code{q}. To use this feature in combination with tablature,
-@code{\tabChordRepetition} is provided.  It preserves the string
-information explicitly given within chord constructs so repeated chords
-get identical tablature representations.
+@code{q}.  In combination with tabulatures, its behavior of removing
+string and finger numbers alongside with other events is cumbersome, so
+you'll want to run
+@example
+\chordRepeats #'(string-number-event fingering-event)
+@end example
+explicitly on music expressions in tabulature using @ref{Chord
+repetition}.  This particular command is so common that it is available
+as @code{\tabChordRepeats}.
 
 @lilypond[quote,verbatim]
-\tabChordRepetition
-
 guitar = \relative c' {
-  r8 <gis\4 cis\3 b\2>~ q4 q8~ q q4
+  r8 <gis-2 cis-3 b-0>~ q4 q8~ q q4
 }
 
 \new StaffGroup <<
   \new Staff {
     \clef "treble_8"
-    \override Voice.StringNumber #'transparent = ##t
     \guitar
   }
   \new TabStaff {
-    \guitar
+    \tabChordRepeats \guitar
   }
 >>
 @end lilypond
 
-
 Ties over a line break are parenthesized by default.  The same holds for
 the second alternative of a repeat.
 
@@ -361,33 +368,107 @@ ties = \relative c' {
 
 @cindex harmonic indications in tablature notation
 @cindex tablature and harmonic indications
-@cindex slides in tablature notation
-@cindex tablature and slides
-
-Harmonic indications and slides can be added to tablature
-notation.
+@funindex \harmonic
+@funindex \harmonicByFret
+@funindex \harmonicByRatio
+
+Harmonic indications can be added to tablature notation as sounding
+pitches:
+
+@lilypond[verbatim,quote]
+\layout { \override Voice.StringNumber.stencil = ##f }
+firstHarmonic = {
+  d'4\4\harmonic
+  g'4\3\harmonic
+  b'2\2\harmonic
+}
+\score {
+  <<
+    \new Staff {
+      \clef "treble_8"
+      \firstHarmonic
+    }
+    \new TabStaff { \firstHarmonic }
+  >>
+}
+@end lilypond
 
-@lilypond[verbatim, quote, relative=1]
-\new TabStaff {
-  \new TabVoice {
-    <c g'\harmonic>4 d\2\glissando e\2
-  }
+Note that the command @code{\harmonic} must always be attached to single
+notes (possibly inside of a chord) instead of whole chords.
+It only makes sense for open-string harmonics
+in the 12th fret. All other harmonics should be calculated by LilyPond.
+This can be achieved by indicating the fret where a finger of the
+fretting hand should touch a string.
+
+@lilypond[verbatim,quote]
+fretHarmonics = {
+  \harmonicByFret #5 d16\4
+  \harmonicByFret #4 d16\4
+  \harmonicByFret #3 d8\4
+  \harmonicByFret #5 <g\3 b\2>2.
+}
+\score {
+  <<
+    \new Staff {
+      \clef "treble_8"
+      \fretHarmonics
+    }
+    \new TabStaff { \fretHarmonics }
+  >>
 }
 @end lilypond
 
+Alternatively, harmonics can be computed by defining the ratio of
+string lengths above and below the harmonic fingering.
 
-@snippets
+@lilypond[verbatim,quote]
+ratioHarmonics = {
+  \harmonicByRatio #1/2 <g\3 b\2 e'\1>4
+  \harmonicByRatio #1/3 <g\3 b\2 e'\1>4
+  \harmonicByRatio #1/4 { g8\3 b8\2 e'4\1 }
+}
+\score {
+  <<
+    \new Staff {
+      \clef "treble_8"
+      \ratioHarmonics
+    }
+    \new TabStaff { \ratioHarmonics }
+  >>
+}
+@end lilypond
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@snippets
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {stem-and-beam-behavior-in-tablature.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {polyphony-in-tablature.ly}
 
+@lilypondfile[verbatim,quote,texidoc,doctitle]
+{open-string-harmonics-in-tablature.ly}
+
+@lilypondfile[verbatim,quote,texidoc,doctitle]
+{fretted-string-harmonics-in-tablature.ly}
+
+@cindex slides in tablature notation
+@cindex tablature and slides
+
+@lilypondfile[verbatim,quote,texidoc,doctitle]
+{slides-in-tablature.ly}
+
+@cindex chord glissandi
+
+@lilypondfile[verbatim,quote,texidoc,doctitle]
+{chord-glissando-in-tablature.ly}
 
 @seealso
 Notation Reference:
-@ref{Stems}.
+@ref{Chord repetition},
+@ref{Glissando},
+@ref{Harmonics},
+@ref{Stems},
+@ref{Written-out repeats}.
 
 Snippets:
 @rlsr{Fretted strings}.
@@ -398,9 +479,7 @@ Internals Reference:
 @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.
@@ -423,6 +502,7 @@ melodia = \partcombine { e4 g g g } { e4 e e e }
 
 Guitar special effects are limited to harmonics and slides.
 
+
 @node Custom tablatures
 @unnumberedsubsubsec Custom tablatures
 
@@ -441,7 +521,7 @@ Guitar special effects are limited to harmonics and slides.
 @cindex tablature, bass
 @cindex tablature, double bass
 
-@funindex StringTunings
+@funindex stringTunings
 
 LilyPond tablature automatically calculates the fret for
 a note based on the string to which the note is assigned.
@@ -458,14 +538,17 @@ written.
 
 @lilypond[quote,ragged-right,verbatim]
 <<
-  \new Staff {
+  \new Voice \with {
+    \override StringNumber.stencil = ##f
+  } {
     \clef "bass_8"
     \relative c, {
       c4 d e f
     }
   }
-  \new TabStaff {
-    \set TabStaff.stringTunings = #bass-tuning
+  \new TabStaff \with {
+    stringTunings = #bass-tuning
+  } {
     \relative c, {
       c4 d e f
     }
@@ -477,21 +560,20 @@ 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 @file{ly/string-tuning-init.ly}.
+are found in @file{ly/string-tunings-init.ly}.
 
-@funindex contextStringTunings
-@funindex \contextStringTunings
+@funindex stringTuning
+@funindex \stringTuning
 @cindex tablature, custom string tunings
 @cindex custom string tunings
 
 Any desired string tuning can be created.  The
-@code{\contextStringTuning} function can be
-used to define a string tuning and set it as the
-@code{stringTunings} for the current context.
-@code{\contextStringTuning} takes two arguments: the
-symbol in which the string tuning will be stored,
-and a chord construct
-that defines the pitches of each string in the tuning.
+@code{\stringTuning} function can be
+used to define a string tuning which can be used
+to set @code{stringTunings} for the current context.
+
+Its argument is a chord construct
+defining the pitches of each string in the tuning.
 The chord construct must be in absolute octave mode,
 see @ref{Absolute octave entry}.  The string
 with the highest number (generally the lowest string) must
@@ -512,7 +594,7 @@ mynotes = {
     \mynotes
   }
   \new TabStaff {
-    \contextStringTuning #'custom-tuning <c' g' d'' a''>
+    \set Staff.stringTunings = \stringTuning <c' g' d'' a''>
     \mynotes
   }
 >>
@@ -521,21 +603,14 @@ mynotes = {
 The @code{stringTunings} property is also used by
 @code{FretBoards} to calculate automatic fret diagrams.
 
-@funindex makeStringTuning
-@funindex \makeStringTuning
-
 String tunings are used as part of the hash key
 for predefined fret diagrams
-(see @ref{Predefined fret diagrams}).  The @code{\makeStringTuning}
-function is used to create a string tuning without setting the
-@code{stringTunings} property in the current context.  The
-arguments to @code{\makeStringTuning} are the symbol to be
-used for the new string tuning and a chord construct used
-to define the tuning.
+(see @ref{Predefined fret diagrams}).
+
 The previous example could also be written as follows:
 
 @lilypond[quote,verbatim]
-\makeStringTuning #'custom-tuning <c' g' d'' a''>
+custom-tuning = \stringTuning <c' g' d'' a''>
 
 mynotes = {
   c'4 e' g' c'' |
@@ -565,36 +640,26 @@ A string pitch in a string tuning list is a LilyPond pitch
 object.  Pitch objects are created with the Scheme function
 @code{ly:make-pitch} (see @ref{Scheme functions}).
 
-If desired, a string tuning can be created as a Scheme
-literal.  The example below recreates the examples above,
-but the string tuning is not saved as a separate object:
-
-@lilypond[quote,verbatim]
-mynotes = {
-  c'4 e' g' c'' |
-  e''4 g'' b'' c'''
-}
-
-<<
-  \new Staff {
-    \clef treble
-    \mynotes
-  }
-  \new TabStaff {
-    \set TabStaff.stringTunings = #`(,(ly:make-pitch 1 5 0)
-				     ,(ly:make-pitch 1 1 0)
-				     ,(ly:make-pitch 0 4 0)
-				     ,(ly:make-pitch 0 0 0))
-    \mynotes
-  }
->>
-@end lilypond
+@code{\stringTuning} creates such an object from chord input.
 
 LilyPond automatically calculates the number of lines in the
 @code{TabStaff} and the number of strings in an automatically
 calculated @code{FretBoard} as the number of elements
 in @code{stringTunings}.
 
+To let all TabStaff contexts use the same custom tuning by default,
+you can use
+
+@example
+\layout @{
+  \context @{
+    \TabStaff
+    stringTunings = \stringTuning \notemode @{ <c' g' d'' a''> @}
+  @}
+@}
+@end example
+
+
 @cindex moderntab clef
 @cindex clef, moderntab
 @cindex clef, tab
@@ -621,7 +686,7 @@ Notation Reference:
 @ref{Scheme functions}.
 
 Installed Files:
-@file{ly/string-tuning-init.ly}
+@file{ly/string-tunings-init.ly},
 @file{scm/tablature.scm}.
 
 Snippets:
@@ -635,6 +700,7 @@ Automatic tablature calculations do not work properly in most
 cases for instruments where string pitches do not vary
 monotonically with string number, such as ukuleles.
 
+
 @node Fret diagram markups
 @unnumberedsubsubsec Fret diagram markups
 
@@ -855,8 +921,7 @@ Fingering indications can be included in the fret-diagram-terse markup string.
     }
   }
   \context Staff {
-    \override Voice.TextScript
-      #'(fret-diagram-details finger-code) = #'below-string
+    \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;"
@@ -930,8 +995,7 @@ capo will be the lowest fret in the fret diagram.
     }
   \context Staff {
     \clef "treble_8"
-    \override Voice.TextScript
-      #'(fret-diagram-details finger-code) = #'below-string
+    \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)
@@ -953,7 +1017,7 @@ capo will be the lowest fret in the fret diagram.
         (place-fret 1 3 3)
       )
     }
-    <c e g c' e'>1^\markup {
+    <c g c' e' g'>1^\markup {
       \fret-diagram-verbose #'(
         (capo 3)
         (mute 6)
@@ -1025,10 +1089,10 @@ markup, the interface properties belong to @code{Voice.TextScript}.
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {changing-fret-orientations.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {customizing-markup-fret-diagrams.ly}
 
 @seealso
@@ -1045,9 +1109,9 @@ Internals Reference:
 @node Predefined fret diagrams
 @unnumberedsubsubsec Predefined fret diagrams
 
-
 @cindex fret diagrams
 @cindex fret diagrams, ukulele
+@cindex fret diagrams, mandolin
 @cindex chord diagrams
 
 @funindex FretBoards
@@ -1076,7 +1140,7 @@ diagrams can be added for other instruments or other tunings
 by following the examples found in
 @file{predefined-guitar-fretboards.ly}.
 
-Fret diagrams for the ukulele are contained in the file
+Fret diagrams for the ukulele are contained in the file @*
 @file{predefined-ukulele-fretboards.ly}.
 
 @lilypond[verbatim, ragged-right, quote]
@@ -1089,7 +1153,25 @@ myChords = \chordmode { a1 a:m a:aug }
 }
 
 \new FretBoards {
-  \set stringTunings = #ukulele-tuning
+  \set Staff.stringTunings = #ukulele-tuning
+  \myChords
+}
+@end lilypond
+
+Fret diagrams for the mandolin are contained in the file @*
+@file{predefined-mandolin-fretboards.ly}.
+
+@lilypond[verbatim, ragged-right, quote]
+\include "predefined-mandolin-fretboards.ly"
+
+myChords = \chordmode { c1 c:m7.5- c:aug }
+
+\new ChordNames {
+  \myChords
+}
+
+\new FretBoards {
+  \set Staff.stringTunings = #mandolin-tuning
   \myChords
 }
 @end lilypond
@@ -1308,19 +1390,18 @@ the interface properties belong to @code{FretBoards.FretBoard}.
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {customizing-fretboard-fret-diagrams.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {defining-predefined-fretboards-for-other-instruments.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {chordchanges-for-fretboards.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {fretboards-alternate-tables.ly}
 
-
 @seealso
 Notation Reference:
 @ref{Custom tablatures},
@@ -1329,9 +1410,10 @@ Notation Reference:
 @ref{Predefined fretboard diagrams}.
 
 Installed Files:
-@file{ly/predefined-guitar-fretboards.ly},
-@file{ly/predefined-guitar-ninth-fretboards.ly},
-@file{ly/predefined-ukulele-fretboards.ly}.
+@file{ly/predefined-guitar-fretboards.ly}, @*
+@file{ly/predefined-guitar-ninth-fretboards.ly}, @*
+@file{ly/predefined-ukulele-fretboards.ly}, @*
+@file{ly/predefined-mandolin-fretboards.ly}.
 
 Snippets:
 @rlsr{Fretted strings}.
@@ -1487,7 +1569,6 @@ diagram, the interface properties belong to
 @code{\predefinedFretboardsOn}.
 @endpredefined
 
-
 @seealso
 Notation Reference:
 @ref{Custom tablatures}.
@@ -1513,40 +1594,38 @@ with non-monotonic tunings.
 @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.
+Right-hand fingerings @var{p-i-m-a} must be entered using
+@code{\rightHandFinger} followed by a number.
 
-@warning{There @strong{must} be a hyphen before
-@code{@bs{}rightHandFinger} and a space before the closing @code{>}.}
+@warning{If the number is entered in Scheme notation, remember to append
+a space before following it with a closing @code{>} or similar.}
 
 @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
+c4\rightHandFinger #1
+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)
+RH=#rightHandFinger
 @end example
 
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {placement-of-right-hand-fingerings.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {fingerings,-string-indications,-and-right-hand-fingerings.ly}
 
-
 @seealso
 Snippets:
 @rlsr{Fretted strings}.
@@ -1586,13 +1665,12 @@ barring indications.
 \clef "treble_8"
 b16 d g b e
 \textSpannerDown
-\override TextSpanner #'(bound-details left text) = #"XII "
+\override TextSpanner.bound-details.left.text = #"XII "
 g16\startTextSpan
 b16 e g e b g\stopTextSpan
 e16 b g d
 @end lilypond
 
-
 @seealso
 Notation Reference:
 @ref{Text spanners}.
@@ -1617,7 +1695,7 @@ text markup.
 @lilypond[quote,ragged-right,verbatim]
 \relative c' {
   \clef "treble_8"
-  \override Staff.NoteHead #'style = #'harmonic-mixed
+  \override Staff.NoteHead.style = #'harmonic-mixed
   d^\markup { \italic { \fontsize #-2 { "harm. 12" }}} <g b>1
 }
 @end lilypond
@@ -1801,22 +1879,21 @@ correct fret numbers for the fifth string:
 @funindex banjo-open-dm-tuning
 @funindex four-string-banjo
 
-A number of common tunings for banjo are predefined in LilyPond:
+A number of common tunings for the five-string banjo are predefined:
 @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 may be converted to four-string tunings using the
 @code{four-string-banjo} function:
 
 @example
 \set TabStaff.stringTunings = #(four-string-banjo banjo-c-tuning)
 @end example
 
-
 @seealso
+Installed Files:
+@file{ly/string-tunings-init.ly}.
+
 Snippets:
 @rlsr{Fretted strings}.
-
-Installed Files:
-@file{scm/output-lib.scm} contains predefined banjo tunings.