Update policy.

diff --git a/Documentation/user/macros.itexi b/Documentation/user/macros.itexi
index a5790a69e445fb4c3fd6e09e6bc2aaa46078909b..ee7bf4b8c8f75cfc67fddfebc1d6bd8387843a4a 100644 (file)
--- 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 31875ef9410a5c3c10726976d086b874f29e0c12..0afbd31c7903c18f95f2f943988fbfad1afb30bf 100644 (file)
--- 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 7b486edf5629da5af2cc9d299bdefbd7afcd2ed6..57acddda6bae062b5537893a76a93be07fc489a3 100644 (file)
--- 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