From 7ca28d45df3c70a0b289670875108532921cd026 Mon Sep 17 00:00:00 2001
From: gpercival <gpercival>
Date: Sun, 14 Sep 2003 02:49:01 +0000
Subject: [PATCH] Add warning about \key and accidentals.

---
 ChangeLog                         |  5 +++++
 Documentation/user/refman.itely   | 23 +++++++++++++++++++++
 Documentation/user/tutorial.itely | 34 +++++++++++++++++++++++++++++--
 3 files changed, 60 insertions(+), 2 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index f391a9416f..30c7098379 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2003-09-14  Graham Percival  <gperlist@shaw.ca>
+
+	* Documentation/user/ tutorial.itely, refman.itely: add warning
+	about \key and accidentals.
+
 2003-09-14  Han-Wen Nienhuys  <hanwen@cs.uu.nl>
 
 	* Documentation/user/*.itely: manual tweaks
diff --git a/Documentation/user/refman.itely b/Documentation/user/refman.itely
index e269cc8a5f..cfbfede34e 100644
--- a/Documentation/user/refman.itely
+++ b/Documentation/user/refman.itely
@@ -828,6 +828,29 @@ The key signature indicates the scale in which a piece is played. It
 is denoted by a set of alterations (flats or sharps) at the start of
 the staff.
 
+WARNING!  The key signature only changes the output, not the music
+itself.  An F-sharp in the key of D major is still an F-sharp, not
+an F -- you must type @code{fis}, not @code{f}.  If you don't modify
+a pitch with @code{-is} or @code{-es}, LilyPond will assume that
+you want a natural note.  See this example:
+
+@quotation
+@example
+\key d \major
+fis4 f fes fis
+g2 fis
+@end example
+@end quotation
+
+@lilypond[noindent]
+\score{ \notes { \relative c'{
+\key d \major
+fis4 f fes fis
+g2 fis
+}}}
+@end lilypond
+
+
 @syntax
 
 Setting or changing the key signature is done with the @code{\key}
diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely
index 183aba4a12..92d1a175c8 100644
--- a/Documentation/user/tutorial.itely
+++ b/Documentation/user/tutorial.itely
@@ -1,4 +1,4 @@
-@c -*-texinfo-*-
+c -*-texinfo-*-
 
 @c TODO:
 @c   * more details about running lilypond; error messages,
@@ -373,7 +373,7 @@ cis1 ees fisis aeses
 @cindex key signature, setting
 
 The key signature is set with the command ``@code{\key}'', followed by
-a pitch and  @code{\major} or @code{\minor}:
+a pitch and @code{\major} or @code{\minor}:
 @quotation
 @example
 \key d \major
@@ -391,6 +391,36 @@ g'
 @end lilypond
 @end quotation
 
+WARNING!  The key signature only affects the way the output is printed,
+not the music itself.  If you type
+
+@example
+@code{
+\key d \major
+d e f g
+}
+@end example
+
+LilyPond will print an F-natural.  An F-sharp in the key of D major
+is still an F-sharp!  To print an F-sharp, you must use @code{fis},
+no matter what the key signature is.  See this example:
+
+@quotation
+@example
+\key d \major
+fis4 f fes fis |
+g2 fis
+@end example
+@end quotation
+
+@lilypond[noindent]
+\score{ \notes { \relative c'{
+\key d \major
+fis4 f fes fis
+g2 fis
+}}}
+@end lilypond
+@separate
 
 @cindex tie
 A tie is created by adding a tilde ``@code{~}'' to the first note
-- 
2.39.5