From: Carl Sorensen <c_sorensen@byu.edu>
Date: Sat, 14 Aug 2010 07:14:09 +0000 (-0600)
Subject: Doc -- Add woodwind diagrams to documentation
X-Git-Tag: release/2.13.31-1~12
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=061fe4a0a6dc06f2d5374f152173cdaac883575f;p=lilypond.git

Doc -- Add woodwind diagrams to documentation
---

diff --git a/Documentation/notation/wind.itely b/Documentation/notation/wind.itely
index 21f5d1aa11..fb30371f08 100644
--- 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
index 0000000000..fb3d05610b
--- /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
index 0000000000..15f8652142
--- /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
index 0000000000..d189e5a6a9
--- /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
index 0000000000..63c97ab7e0
--- /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
index 0000000000..c9615b58d8
--- /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
index 0000000000..613391fdcf
--- /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
index 0000000000..877e7ddd13
--- /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
index 0000000000..9cae196a18
--- /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
+        #'()
+    }
+  }
+}