From e210543007af9134aa5b84be61537e64bce35f25 Mon Sep 17 00:00:00 2001
From: Mark Polesky <address@hidden>
Date: Sat, 25 Sep 2010 18:27:51 -0700
Subject: [PATCH] Doc: CG 4.3.6: Clarify usage of @code, @var, etc.

---
 Documentation/contributor/doc-work.itexi |   51 ++++++++++++++++++++----------
 1 files changed, 34 insertions(+), 17 deletions(-)

diff --git a/Documentation/contributor/doc-work.itexi b/Documentation/contributor/doc-work.itexi
index abd8c16..53377fa 100644
--- a/Documentation/contributor/doc-work.itexi
+++ b/Documentation/contributor/doc-work.itexi
@@ -604,17 +604,20 @@ external url.  Use within an @code{@@example ... @@end example}.
 @item
 @code{@@address@hidden@address@hidden, @code{@@address@hidden@address@hidden ---
 
-Use the @code{@@address@hidden@address@hidden command for individual
-language-specific tokens (keywords, commands, engravers, scheme
-symbols, etc.).  Ideally, a single @code{@@address@hidden@address@hidden block
-should fit within one line in the PDF output.  Use the
address@hidden@@address@hidden@address@hidden command when you have a short example of
-user input, unless it constitutes an entire @code{@@item} by
-itself, in which case @code{@@address@hidden@address@hidden is preferable.
-Otherwise, both should only be used when part of a larger sentence
-within a paragraph or @code{@@item}.  Never use a
address@hidden@@address@hidden@address@hidden or @code{@@address@hidden@address@hidden block as a
-free-standing paragraph; use @code{@@example} instead.
+Use the @code{@@address@hidden@address@hidden command when referring to
+individual language-specific tokens (keywords, commands,
+engravers, scheme symbols, etc.) in the text.  Ideally, a single
address@hidden@@address@hidden@address@hidden block should fit within one line in the
+PDF output.
+
+Use the @code{@@address@hidden@address@hidden command when you have a short
+example of user input, unless it constitutes an entire
address@hidden@@item} by itself, in which case @code{@@address@hidden@address@hidden is
+preferable.  Otherwise, both should only be used when part of a
+larger sentence within a paragraph or @code{@@item}.  Do not use
address@hidden@@address@hidden@address@hidden or @code{@@address@hidden@address@hidden inside an
address@hidden@@example} block, and do not use either as a free-standing
+paragraph; use @code{@@example} instead.
 
 A single unindented line in the PDF has space for about 79
 fixed-width characters (76 if indented).  Within an @code{@@item}
@@ -660,8 +663,9 @@ so the example above would be coded as
 @address@hidden@@address@hidden@@address@hidden@@address@hidden@@address@hidden@}relative c''@address@hidden@}}}.
 
 @item
address@hidden@@address@hidden@address@hidden --- Use for command-line commands (eg.
address@hidden@@address@hidden@}}).
address@hidden@@address@hidden@address@hidden --- Use when referring to command-line
+commands within the text (eg. @samp{@@address@hidden@}}).  Do
+not use inside an @code{@@example} block.
 
 @item
 @code{@@example} --- Use for examples of program code.  Do not add
@@ -700,11 +704,14 @@ running into the PDF margin.  Each additional level of
 @code{@@smallexample} line by about 5 columns.
 
 @item
address@hidden@@address@hidden@address@hidden --- Use for filenames and directories.
address@hidden@@address@hidden@address@hidden --- Use when referring to filenames and
+directories in the text.  Do not use inside an @code{@@example}
+block.
 
 @item
address@hidden@@address@hidden@address@hidden --- Use for options to command-line
-commands (eg. @samp{@@address@hidden@}}).
address@hidden@@address@hidden@address@hidden --- Use when referring to command-line
+options in the text (eg. @samp{@@address@hidden@}}).  Do not use
+inside an @code{@@example} block.
 
 @item
 @code{@@verbatim} --- Prints the block exactly as it appears in
@@ -814,7 +821,17 @@ Only use once per subsection per term.
 backslash (\), you must use @samp{@@address@hidden@}}.
 
 @item
address@hidden@@address@hidden@address@hidden --- Use for variables.
address@hidden@@address@hidden@address@hidden --- Use for metasyntactic variables (such
+as @address@hidden, @address@hidden, @address@hidden, etc.).
+In most cases, when the @code{@@address@hidden@address@hidden command appears in
+the text (and not in an @code{@@example} block) it should be
+wrapped with an appropriate texinfo code-highlighting command
+(such as @code{@@code}, @code{@@samp}, @code{@@file},
address@hidden@@command}, etc.).  For example:
address@hidden@@address@hidden@@address@hidden@address@hidden,
address@hidden@@address@hidden@@address@hidden@address@hidden,
address@hidden@samp{@@address@hidden checkout @@address@hidden@address@hidden, etc.  This
+improves readability in the PDF and HTML output.
 
 @item
 @code{@@address@hidden@}} --- Return the current LilyPond version
-- 
1.6.3.3