Graham Percival wrote:
> Could either of you shove this into the doc-work chapter
> of the Contributor's Guide? Possibly making a new section
> for "Doc policy rationale", or else just wherever the
> @code{} bit is discussed.
Okay to push?
- Mark
From 67f9a939733bf8b8792aaff54969bc30bcf63cb3 Mon Sep 17 00:00:00 2001
From: Mark Polesky <markpole...@yahoo.com>
Date: Fri, 24 Sep 2010 09:13:31 -0700
Subject: [PATCH] Doc: CG 4.3.6: Clarify usage of @code, @var, etc.
---
Documentation/contributor/doc-work.itexi | 49 +++++++++++++++++++----------
1 files changed, 32 insertions(+), 17 deletions(-)
diff --git a/Documentation/contributor/doc-work.itexi
b/Documentation/contributor/doc-work.itexi
index abd8c16..e722167 100644
--- a/Documentation/contributor/doc-work.itexi
+++ b/Documentation/contributor/doc-work.itexi
@@ -604,17 +604,23 @@ external url. Use within an @code{@@example ... @@end
example}.
@item
@code{@@c...@{@dot...@}}, @code{@@s...@{@dot...@}} ---
-Use the @code{@@c...@{@dot...@}} command for individual
-language-specific tokens (keywords, commands, engravers, scheme
-symbols, etc.). Ideally, a single @code{@@c...@{@dot...@}} block
-should fit within one line in the PDF output. Use the
-...@code{@@s...@{@dot...@}} command when you have a short example of
-user input, unless it constitutes an entire @code{@@item} by
-itself, in which case @code{@@c...@{@dot...@}} is preferable.
-Otherwise, both should only be used when part of a larger sentence
-within a paragraph or @code{@@item}. Never use a
-...@code{@@c...@{@dot...@}} or @code{@@s...@{@dot...@}} block as a
-free-standing paragraph; use @code{@@example} instead.
+Use the @code{@@c...@{@dot...@}} command when referring to
+individual language-specific tokens (keywords, commands,
+engravers, scheme symbols, etc.) in the text. Also, metasyntactic
+variables mentioned in the text (such as @co...@var{foo}},
+...@code{@var{bar}}, @co...@var{arg1}}, etc.) should be entered with
+...@code{@@c...@{@@v...@{@dot...@}@}}. Ideally, a single
+...@code{@@c...@{@dot...@}} block should fit within one line in the
+PDF output.
+
+Use the @code{@@s...@{@dot...@}} command when you have a short
+example of user input, unless it constitutes an entire
+...@code{@@item} by itself, in which case @code{@@c...@{@dot...@}} is
+preferable. Otherwise, both should only be used when part of a
+larger sentence within a paragraph or @code{@@item}. Do not use
+...@code{@@c...@{@dot...@}} or @code{@@s...@{@dot...@}} inside an
+...@code{@@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 +666,9 @@ so the example above would be coded as
@q...@code{@@q...@{@@w...@{@@c...@{@@b...@{@}relative c''@}...@}@}}}.
@item
-...@code{@@comm...@{@dot...@}} --- Use for command-line commands (eg.
-...@samp{@@comm...@{lilypond-book@}}).
+...@code{@@comm...@{@dot...@}} --- Use when referring to command-line
+commands within the text (eg. @samp{@@comm...@{convert-ly@}}). Do
+not use inside an @code{@@example} block.
@item
@code{@@example} --- Use for examples of program code. Do not add
@@ -700,11 +707,14 @@ running into the PDF margin. Each additional level of
@code{@@smallexample} line by about 5 columns.
@item
-...@code{@@f...@{@dot...@}} --- Use for filenames and directories.
+...@code{@@f...@{@dot...@}} --- Use when referring to filenames and
+directories in the text. Do not use inside an @code{@@example}
+block.
@item
-...@code{@@opt...@{@dot...@}} --- Use for options to command-line
-commands (eg. @samp{@@opt...@{--format@}}).
+...@code{@@opt...@{@dot...@}} --- Use when referring to command-line
+options in the text (eg. @samp{@@opt...@{--format@}}). Do not use
+inside an @code{@@example} block.
@item
@code{@@verbatim} --- Prints the block exactly as it appears in
@@ -814,7 +824,12 @@ Only use once per subsection per term.
backslash (\), you must use @samp{@@b...@{@}}.
@item
-...@code{@@v...@{@dot...@}} --- Use for variables.
+...@code{@@v...@{@dot...@}} --- Use for metasyntactic variables (such
+as @co...@var{foo}}, @co...@var{bar}}, @co...@var{arg1}}, etc.).
+When referring to variables in the text, use
+...@code{@@c...@{@@v...@{@dot...@}@}}, unless the
+...@code{@@v...@{@dot...@}} is already within another fixed-width
+command such as @code{@@s...@{@dot...@}}.
@item
@code{@@vers...@{@}} --- Return the current LilyPond version
--
1.6.3.3
_______________________________________________
lilypond-devel mailing list
lilypond-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-devel
