Doc -- Add woodwind diagrams to documentation

diff --git a/Documentation/notation/wind.itely b/Documentation/notation/wind.itely
index 21f5d1aa118d54ebe6f2570b85cde3ff66ecd5a0..fb30371f08eb56e5393f1f75055efc62afb14f6f 100644 (file)
--- a/Documentation/notation/wind.itely
+++ b/Documentation/notation/wind.itely
@@ -20,6 +20,7 @@ writing for winds.
 @menu
 * Common notation for wind instruments::
 * Bagpipes::
+* Woodwinds::
 @end menu
 
 @node Common notation for wind instruments
@@ -233,3 +234,170 @@ notation.
 
 @seealso
 @rlsr{Winds}.
+
+@node Woodwinds
+@subsection Woodwinds
+
+This section describes notation specifically for woodwinds.
+
+@menu
+* Woodwind diagrams::
+@end menu
+
+@node Woodwind diagrams
+@subsubsection Woodwind diagrams
+
+Woodwind diagrams can be used to indicate the fingering to be used
+to play specific notes.  Woodwind diagrams are available for most woodwind
+instruments.
+
+Woodwind diagrams are available for the following instruments:
+
+@itemize
+@item piccolo
+@item flute
+@item oboe
+@item clarinet
+@item bass clarinet
+@item saxophone
+@item basson
+@item contrabassoon
+@end itemize
+
+@noindent
+The diagrams and the scheme instrument names are shown in the snippet below.
+
+Woodwind diagrams are created as markups:
+
+
+@lilypond[verbatim, quote, relative=2]
+c1^ \markup \woodwind-diagram #'piccolo #'((lh . (gis))
+                                           (cc . (one three))
+                                           (rh . (ees)))
+@end lilypond
+
+Keys can be open, partially-covered, ring-depressed, or fully covered:
+
+@lilypond [verbatim, quote, relative=2]
+\textLengthOn
+c1^ \markup \center-column {
+  "one quarter"
+  \woodwind-diagram #'flute #'((cc . (one1q))
+                                  (lh . ())
+                                  (rh . ()))
+}
+c1^ \markup \center-column {
+  "one half"
+  \woodwind-diagram #'flute #'((cc . (one1h))
+                                  (lh . ())
+                                  (rh . ()))
+}
+c1^ \markup \center-column {
+  "three quarter"
+  \woodwind-diagram #'flute #'((cc . (one3q))
+                                  (lh . ())
+                                  (rh . ()))
+}
+c1^ \markup \center-column {
+  "ring"
+  \woodwind-diagram #'flute #'((cc . (oneR))
+                                  (lh . ())
+                                  (rh . ()))
+}
+c1^ \markup \center-column {
+  "full"
+  \woodwind-diagram #'flute #'((cc . (oneF two))
+                                  (lh . ())
+                                  (rh . ()))
+}
+@end lilypond
+
+Trills are indicated in the woodwind diagrams as shaded keys:
+
+@lilypond [verbatim, quote, relative=2]
+c1^ \markup \woodwind-diagram #'bass-clarinet
+                              #'((cc . (threeT four))
+                                 (lh . ())
+                                 (rh . (b fis)))
+@end lilypond
+
+A variety of trills can be displayed:
+
+@lilypond [verbatim, quote, relative=2]
+\textLengthOn
+c1^ \markup \center-column {
+  "one quarter to ring"
+  \woodwind-diagram #'flute #'((cc . (one1qTR))
+                                  (lh . ())
+                                  (rh . ()))
+}
+c1^ \markup \center-column {
+  "ring to shut"
+  \woodwind-diagram #'flute #'((cc . (oneTR))
+                                  (lh . ())
+                                  (rh . ()))
+}
+c1^ \markup \center-column {
+  "ring to open"
+  \woodwind-diagram #'flute #'((cc . (oneRT))
+                                  (lh . ())
+                                  (rh . ()))
+}
+c1^ \markup \center-column {
+  "open to shut"
+  \woodwind-diagram #'flute #'((cc . (oneT))
+                                  (lh . ())
+                                  (rh . ()))
+}
+c1^ \markup \center-column {
+  "one quarter to three quarters"
+  \woodwind-diagram #'flute #'((cc . (one1qT3q))
+                                  (lh . ())
+                                  (rh . ()))
+}
+@end lilypond
+
+The list of all possible keys and settings for a given instrument
+can be displayed on the console or in the log file, although they
+will not show up in the music output:
+
+@lilypond[verbatim, quote]
+
+#(print-keys-verbose 'flute)
+
+@end lilypond
+
+New diagrams can be created by following the patterns in
+@file{scm/define-woodwind-diagrams.scm} and
+@file{scm/display-woodwind-diagrams.scm}.  However, this will
+require Scheme ability and may not be accessible to all users.
+
+@predefined
+@endpredefined
+
+@snippets
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{woodwind-diagrams-listing.ly}
+
+@lilypondfile[verbatim, lilyquote, texidoc, doctitle]
+{graphical-and-text-woodwind-diagrams.ly}
+
+@lilypondfile[verbatim, lilyquote, texidoc, doctitle]
+{changing-the-size-of-woodwind-diagrams.ly}
+
+@lilypondfile[verbatim, lilyquote, texidoc, doctitle]
+{woodwind-diagrams-key-lists.ly}
+
+@seealso
+
+Installed Files:
+@file{scm/define-woodwind-diagrams.scm},
+@file{scm/display-woodwind-diagrams.scm}.
+
+Snippets: @rlsr{Winds}.
+
+Internals Reference:
+@rinternals{TextScript},
+@rinternals{instrument-specific-markup-interface}.
+
+@knownissues

diff --git a/Documentation/snippets/changing-the-size-of-woodwind-diagrams.ly b/Documentation/snippets/changing-the-size-of-woodwind-diagrams.ly
new file mode 100644 (file)
index 0000000..fb3d056
--- /dev/null
+++ b/Documentation/snippets/changing-the-size-of-woodwind-diagrams.ly
@@ -0,0 +1,36 @@
+% Do not edit this file; it is automatically
+% generated from Documentation/snippets/new
+% This file is in the public domain.
+%% Note: this file works from version 2.13.31
+\version "2.13.31"
+
+\header {
+  lsrtags="Winds"
+  texidoc="
+The size and thickness of woodwind diagrams can be changed.
+"
+
+  doctitle = "Changing the size of woodwind diagrams"
+} % begin verbatim
+
+
+\relative c'' {
+  \textLengthOn
+  c1^\markup
+    \woodwind-diagram
+      #'piccolo
+      #'()
+
+  c^\markup
+    \override #'(size . 1.5) {
+      \woodwind-diagram
+        #'piccolo
+        #'()
+    }
+  c^\markup
+    \override #'(thickness . 0.15) {
+      \woodwind-diagram
+        #'piccolo
+        #'()
+    }
+}

diff --git a/Documentation/snippets/graphical-and-text-woodwind-diagrams.ly b/Documentation/snippets/graphical-and-text-woodwind-diagrams.ly
new file mode 100644 (file)
index 0000000..15f8652
--- /dev/null
+++ b/Documentation/snippets/graphical-and-text-woodwind-diagrams.ly
@@ -0,0 +1,35 @@
+% Do not edit this file; it is automatically
+% generated from Documentation/snippets/new
+% This file is in the public domain.
+%% Note: this file works from version 2.13.31
+\version "2.13.31"
+
+\header {
+  lsrtags="Winds"
+  texidoc="
+In may cases, the keys other than the central column can be
+displayed by key name as well as by graphical means.
+"
+
+  doctitle = "Graphical and text woodwind diagrams"
+} % begin verbatim
+
+
+\relative c'' {
+  \textLengthOn
+  c1^\markup
+    \woodwind-diagram
+      #'piccolo
+      #'((cc . (one three))
+         (lh . (gis))
+         (rh . (ees)))
+
+  c^\markup
+    \override #'(graphical . #f) {
+      \woodwind-diagram
+        #'piccolo
+        #'((cc . (one three))
+           (lh . (gis))
+           (rh . (ees)))
+    }
+}

diff --git a/Documentation/snippets/new/changing-the-size-of-woodwind-diagrams.ly b/Documentation/snippets/new/changing-the-size-of-woodwind-diagrams.ly
new file mode 100644 (file)
index 0000000..d189e5a
--- /dev/null
+++ b/Documentation/snippets/new/changing-the-size-of-woodwind-diagrams.ly
@@ -0,0 +1,31 @@
+\version "2.13.31"
+
+\header {
+  lsrtags="Winds"
+  texidoc="
+The size and thickness of woodwind diagrams can be changed.
+"
+
+  doctitle = "Changing the size of woodwind diagrams"
+}
+
+\relative c'' {
+  \textLengthOn
+  c1^\markup
+    \woodwind-diagram
+      #'piccolo
+      #'()
+
+  c^\markup
+    \override #'(size . 1.5) {
+      \woodwind-diagram
+        #'piccolo
+        #'()
+    }
+  c^\markup
+    \override #'(thickness . 0.15) {
+      \woodwind-diagram
+        #'piccolo
+        #'()
+    }
+}

diff --git a/Documentation/snippets/new/graphical-and-text-woodwind-diagrams.ly b/Documentation/snippets/new/graphical-and-text-woodwind-diagrams.ly
new file mode 100644 (file)
index 0000000..63c97ab
--- /dev/null
+++ b/Documentation/snippets/new/graphical-and-text-woodwind-diagrams.ly
@@ -0,0 +1,30 @@
+\version "2.13.31"
+
+\header {
+  lsrtags="Winds"
+  texidoc="
+In may cases, the keys other than the central column can be
+displayed by key name as well as by graphical means.
+"
+
+  doctitle = "Graphical and text woodwind diagrams"
+}
+
+\relative c'' {
+  \textLengthOn
+  c1^\markup
+    \woodwind-diagram
+      #'piccolo
+      #'((cc . (one three))
+         (lh . (gis))
+         (rh . (ees)))
+
+  c^\markup
+    \override #'(graphical . #f) {
+      \woodwind-diagram
+        #'piccolo
+        #'((cc . (one three))
+           (lh . (gis))
+           (rh . (ees)))
+    }
+}

diff --git a/Documentation/snippets/new/woodwind-diagrams-key-lists.ly b/Documentation/snippets/new/woodwind-diagrams-key-lists.ly
new file mode 100644 (file)
index 0000000..c9615b5
--- /dev/null
+++ b/Documentation/snippets/new/woodwind-diagrams-key-lists.ly
@@ -0,0 +1,25 @@
+\version "2.13.24"
+
+\header {
+  lsrtags = "Winds"
+
+  texidoc="
+The snippet below produces a list of all possible keys and key
+settings for woodwind diagrams as defined in
+@file{scm/define-woodwind-diagrams.scm}.  The list will be displayed
+on the console and in the log file, but not in the music.
+"
+  doctitle = "Woodwind diagrams key lists"
+}
+
+#(print-keys-verbose 'piccolo)
+#(print-keys-verbose 'flute)
+#(print-keys-verbose 'flute-b-extension)
+#(print-keys-verbose 'oboe)
+#(print-keys-verbose 'clarinet)
+#(print-keys-verbose 'bass-clarinet)
+#(print-keys-verbose 'low-bass-clarinet)
+#(print-keys-verbose 'saxophone)
+#(print-keys-verbose 'baritone-saxophone)
+#(print-keys-verbose 'bassoon)
+#(print-keys-verbose 'contrabassoon)

diff --git a/Documentation/snippets/new/woodwind-diagrams-listing.ly b/Documentation/snippets/new/woodwind-diagrams-listing.ly
new file mode 100644 (file)
index 0000000..613391f
--- /dev/null
+++ b/Documentation/snippets/new/woodwind-diagrams-listing.ly
@@ -0,0 +1,95 @@
+\version "2.13.31"
+
+\header {
+  lsrtags="Winds"
+  texidoc="
+The following music shows all of the woodwind diagrams currently
+defined in LilyPond.
+"
+  doctitle = "Woodwind diagrams listing"
+
+}
+
+\relative c' {
+  \textLengthOn
+  c1^
+  \markup {
+    \center-column {
+      'piccolo
+      " "
+       \woodwind-diagram
+                  #'piccolo
+                  #'()
+    }
+  }
+
+  c1^
+  \markup {
+    \center-column {
+       'flute
+       " "
+       \woodwind-diagram
+          #'flute
+          #'()
+    }
+  }
+  c1^\markup {
+    \center-column {
+      'oboe
+      " "
+      \woodwind-diagram
+        #'oboe
+        #'()
+    }
+  }
+
+  c1^\markup {
+    \center-column {
+      'clarinet
+      " "
+      \woodwind-diagram
+        #'clarinet
+        #'()
+    }
+  }
+
+  c1^\markup {
+    \center-column {
+      'bass-clarinet
+      " "
+      \woodwind-diagram
+        #'bass-clarinet
+        #'()
+    }
+  }
+
+  c1^\markup {
+    \center-column {
+      'saxophone
+      " "
+      \woodwind-diagram
+        #'saxophone
+        #'()
+    }
+  }
+
+  c1^\markup {
+    \center-column {
+      'bassoon
+      " "
+      \woodwind-diagram
+        #'bassoon
+        #'()
+    }
+  }
+
+  c1^\markup {
+    \center-column {
+      'contrabassoon
+      " "
+      \woodwind-diagram
+        #'contrabassoon
+        #'()
+    }
+  }
+}

diff --git a/Documentation/snippets/woodwind-diagrams-key-lists.ly b/Documentation/snippets/woodwind-diagrams-key-lists.ly
new file mode 100644 (file)
index 0000000..877e7dd
--- /dev/null
+++ b/Documentation/snippets/woodwind-diagrams-key-lists.ly
@@ -0,0 +1,30 @@
+% Do not edit this file; it is automatically
+% generated from Documentation/snippets/new
+% This file is in the public domain.
+%% Note: this file works from version 2.13.24
+\version "2.13.31"
+
+\header {
+  lsrtags = "Winds"
+
+  texidoc="
+The snippet below produces a list of all possible keys and key
+settings for woodwind diagrams as defined in
+@file{scm/define-woodwind-diagrams.scm}.  The list will be displayed
+on the console and in the log file, but not in the music.
+"
+  doctitle = "Woodwind diagrams key lists"
+} % begin verbatim
+
+
+#(print-keys-verbose 'piccolo)
+#(print-keys-verbose 'flute)
+#(print-keys-verbose 'flute-b-extension)
+#(print-keys-verbose 'oboe)
+#(print-keys-verbose 'clarinet)
+#(print-keys-verbose 'bass-clarinet)
+#(print-keys-verbose 'low-bass-clarinet)
+#(print-keys-verbose 'saxophone)
+#(print-keys-verbose 'baritone-saxophone)
+#(print-keys-verbose 'bassoon)
+#(print-keys-verbose 'contrabassoon)

diff --git a/Documentation/snippets/woodwind-diagrams-listing.ly b/Documentation/snippets/woodwind-diagrams-listing.ly
new file mode 100644 (file)
index 0000000..9cae196
--- /dev/null
+++ b/Documentation/snippets/woodwind-diagrams-listing.ly
@@ -0,0 +1,100 @@
+% Do not edit this file; it is automatically
+% generated from Documentation/snippets/new
+% This file is in the public domain.
+%% Note: this file works from version 2.13.31
+\version "2.13.31"
+
+\header {
+  lsrtags="Winds"
+  texidoc="
+The following music shows all of the woodwind diagrams currently
+defined in LilyPond.
+"
+  doctitle = "Woodwind diagrams listing"
+
+} % begin verbatim
+
+
+\relative c' {
+  \textLengthOn
+  c1^
+  \markup {
+    \center-column {
+      'piccolo
+      " "
+       \woodwind-diagram
+                  #'piccolo
+                  #'()
+    }
+  }
+
+  c1^
+  \markup {
+    \center-column {
+       'flute
+       " "
+       \woodwind-diagram
+          #'flute
+          #'()
+    }
+  }
+  c1^\markup {
+    \center-column {
+      'oboe
+      " "
+      \woodwind-diagram
+        #'oboe
+        #'()
+    }
+  }
+
+  c1^\markup {
+    \center-column {
+      'clarinet
+      " "
+      \woodwind-diagram
+        #'clarinet
+        #'()
+    }
+  }
+
+  c1^\markup {
+    \center-column {
+      'bass-clarinet
+      " "
+      \woodwind-diagram
+        #'bass-clarinet
+        #'()
+    }
+  }
+
+  c1^\markup {
+    \center-column {
+      'saxophone
+      " "
+      \woodwind-diagram
+        #'saxophone
+        #'()
+    }
+  }
+
+  c1^\markup {
+    \center-column {
+      'bassoon
+      " "
+      \woodwind-diagram
+        #'bassoon
+        #'()
+    }
+  }
+
+  c1^\markup {
+    \center-column {
+      'contrabassoon
+      " "
+      \woodwind-diagram
+        #'contrabassoon
+        #'()
+    }
+  }
+}