From f9699ef192963358d63ebfa9a26f9862e0a1a563 Mon Sep 17 00:00:00 2001
From: Graham Percival <graham@percival-music.ca>
Date: Thu, 11 Oct 2007 14:40:43 -0700
Subject: [PATCH] Update policy.

---
 Documentation/user/macros.itexi  |  4 ++++
 Documentation/user/pitches.itely |  6 +++---
 Documentation/user/policy.txt    | 23 ++++++++++++++++-------
 3 files changed, 23 insertions(+), 10 deletions(-)

diff --git a/Documentation/user/macros.itexi b/Documentation/user/macros.itexi
index a5790a69e4..ee7bf4b8c8 100644
--- a/Documentation/user/macros.itexi
+++ b/Documentation/user/macros.itexi
@@ -31,6 +31,10 @@
 @end quotation
 @end macro
 
+@macro notation{TEXT}
+@var{\TEXT\}
+@end macro
+
 
 
 @c   **** Headings in a doc subsection ****
diff --git a/Documentation/user/pitches.itely b/Documentation/user/pitches.itely
index 31875ef941..0afbd31c79 100644
--- a/Documentation/user/pitches.itely
+++ b/Documentation/user/pitches.itely
@@ -567,9 +567,9 @@ mus = { c d e f }
 
 @code{\transpose} may also be used to input written notes for a
 transposing instrument.  Pitches are normally entered into
-LilyPond in C (or @q{concert pitch}), but they may be entered in
-another key.  For example, when entering music for a B-flat
-trumpet which begins on concert D, one would write
+LilyPond in C (or @notation{concert pitch}), but they may be
+entered in another key.  For example, when entering music for a
+B-flat trumpet which begins on concert D, one would write
 
 @example
 \transpose c bes @{ e4 @dots{} @}
diff --git a/Documentation/user/policy.txt b/Documentation/user/policy.txt
index 7b486edf56..57acddda6b 100644
--- a/Documentation/user/policy.txt
+++ b/Documentation/user/policy.txt
@@ -60,8 +60,8 @@ main docs
 @seealso
 @refbugs
 
-* You must include a @seealso with at least one link to @lsrdir{}.
-  The order of items inside the @seealso section is
+* You _must_ include a @seealso.  The order of items inside the
+  @seealso section is
 
     Music glossary: @rgloss{foo}, @rgloss{bar}.
 
@@ -71,7 +71,7 @@ main docs
 
     Program reference: @internalsref{fazzle}, @internalsref{booar}.
 
-  ("Snippets" is required; the others are optional)
+  ("Snippets" is REQUIRED; the others are optional)
 
 * @commonprop and @refbugs are optional.
 
@@ -179,11 +179,20 @@ main docs
 
   Do not use @itemize @bullet.
 
-* Use @q instead of `...' and @qq instead of ``...''.  The latter macro
-  should be used with care since we use `...' as the default quoting
-  throughout the manual, except for things related to direct speech.
+* Specially-marked text:
 
-  In most cases, you should use @code{} or @samp{} instead.
+    @code{}: actual lilypond code or property/context names.
+    @samp{}: ditto, for single-letter code.
+	@notation{}: refers to pieces of notation, such as
+	  "@notation{crescendo} is often abbreviated as
+      @notation{cresc.}"  This should also be used to refer to
+      specific lyrics ("the @notation{A - men} is centered...")
+	@q{}: used for `vague' terms in English (and other natural
+      languages).
+	@qq{}: only for actual quotes -- i.e. "he said" or "she
+      wrote".
+
+* @warning{} produces a "Note: " box.  Use for important messages.
 
 
 %%%%% READABILITY
-- 
2.39.2