+@rlsr{Winds}.
+
+@node Woodwinds
+@subsection Woodwinds
+
+This section discusses notation specifically for woodwind instruments.
+
+@menu
+* Woodwind diagrams::
+@end menu
+
+@node Woodwind diagrams
+@subsubsection Woodwind diagrams
+
+Woodwind diagrams can be used to indicate the fingering to be used
+for specific notes and are available for the following instruments:
+
+@itemize
+@item piccolo
+@item flute
+@item oboe
+@item clarinet
+@item bass clarinet
+@item saxophone
+@item bassoon
+@item contrabassoon
+@end itemize
+
+@noindent
+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 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}.