Merge branch 'lilypond/translation' of ssh://git.sv.gnu.org/srv/git/lilypond into...

[lilypond.git] / Documentation / contributor / doc-work.itexi

diff --git a/Documentation/contributor/doc-work.itexi b/Documentation/contributor/doc-work.itexi
index 16f9f0f7e6b53e66d0e034de5e486ebf6e74b098..c5554ad4409c9b6cb771f6cfab9f6497c53aef2e 100644 (file)
--- a/Documentation/contributor/doc-work.itexi
+++ b/Documentation/contributor/doc-work.itexi
@@ -284,14 +284,7 @@ construct.  These are easily constructed with automatic tools; see
 @itemize
 
 @item
-Use two spaces for indentation in lilypond examples.  (no
-tabs)
-
-@item
-All text strings should be prefaced with #.  LilyPond does
-not strictly require this, but it is helpful to get users
-accustomed to this scheme construct.  ie @code{\set
-Staff.instrumentName = #"cello"}
+Use two spaces for indentation in lilypond examples (no tabs).
 
 @item
 All engravers should have double-quotes around them:
@@ -300,8 +293,22 @@ All engravers should have double-quotes around them:
 \consists "Spans_arpeggio_engraver"
 @end example
 
-Again, LilyPond does not strictly require this, but it is a useful
-standard to follow.
+LilyPond does not strictly require this, but it is a useful
+convention to follow.
+
+@item
+All context or layout object strings should be prefaced with @code{#}.
+Again, LilyPond does not strictly require this, but it is helpful
+to get users accustomed to this scheme construct.  i.e. @code{\set
+Staff.instrumentName = #"cello"}
+
+@item
+Try to avoid using @code{#'} or @code{#`} within when describing
+context or layout properties outside of an @code{@@example} or @code{@@lilypond}, unless
+the description explicitly requires it.
+
+ie @qq{...setting the @code{transparent} property leaves the object where it
+is, but makes it invisible.}
 
 @item
 If possible, only write one bar per line.
@@ -528,7 +535,9 @@ command ;)
 @unnumberedsubsubsec Cross references
 
 Enter the exact @code{@@node} name of the target reference between
-the brackets (eg.@tie{}@w{@samp{@@ref@{Syntax survey@}}}).
+the brackets (eg.@tie{}@w{@samp{@@ref@{Syntax survey@}}}).  Do not
+split a cross-reference across two lines -- this causes the
+cross-reference to be rendered incorrectly in html documents.
 
 @itemize
 @item