Remove obsolete regression test.

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

diff --git a/Documentation/contributor/doc-work.itexi b/Documentation/contributor/doc-work.itexi
index 5585ca921dc9af846c4af2f35499040dc513c80f..16f9f0f7e6b53e66d0e034de5e486ebf6e74b098 100644 (file)
--- a/Documentation/contributor/doc-work.itexi
+++ b/Documentation/contributor/doc-work.itexi
@@ -62,6 +62,9 @@ the main portion of NR 1+2) may also seem counter-intuitive, but
 they also stem from attempting to find the most effective use of
 limited documentation help.
 
+Before undertaking any large documentation work, contributors are
+encouraged to contact the @ref{Meisters, Documentation Meister}.
+
 
 @node Documentation suggestions
 @section Documentation suggestions
@@ -229,11 +232,25 @@ level.  Sections are created with
 
 @itemize
 @item
-Please leave two blank lines above a @@node; this makes it
+Please leave two blank lines above a @code{@@node}; this makes it
 easier to find sections in texinfo.
 
 @item
-If a heading is desired without creating a node, please use
+Do not use any @code{@@} commands for a @code{@@node}.  They may be
+used for any @code{@@sub...} sections or headings however.
+
+@example
+not:
+@@node @@code@{Foo@} Bar
+@@subsection @@code@{Foo@} Bar
+
+but instead:
+@@node Foo Bar
+@@subsection @@code@{Foo@} Bar
+@end example
+
+@item
+If a heading is desired without creating a @code{@@node}, please use
 the following:
 
 @example
@@ -241,9 +258,9 @@ the following:
 @end example
 
 @item
-Sectioning commands (@@node and @@section) must not appear
-inside an @@ignore.  Separate those commands with a space, ie
-@@n@tie{}ode.
+Sectioning commands (@code{@@node} and @code{@@section}) must not appear
+inside an @code{@@ignore}.  Separate those commands with a space, ie
+@code{@@n}@tie{}@code{ode}.
 
 @end itemize
 
@@ -359,10 +376,32 @@ Comments should go on their own line, and be placed before
 the line(s) to which they refer.
 
 @item
-Add extra spaces around @{ @} marks; ie
+For clarity, always use @{ @} marks even if they are not technically
+required; ie
+
+@example
+not:
+
+\context Voice \repeat unfold 2 \relative c' @{
+  c2 d
+@}
+
+but instead:
+
+\context Voice @{
+  \repeat unfold 2 @{
+    \relative c' @{
+      c2 d
+    @}
+  @}
+@}
+@end example
+
+@item
+Add a space around @{ @} marks; ie
 
 @example
-not:          \chordmode @{c e g@}
+not:          \chordmode@{c e g@}
 but instead:  \chordmode @{ c e g @}
 @end example
 
@@ -539,7 +578,13 @@ the brackets (eg.@tie{}@w{@samp{@@ref@{Syntax survey@}}}).
 
 @item
 @code{@@uref@{@var{URL}[, @var{link text}]@}} --- link to an
-external url.
+external url.  Use within an @code{@@example ... @@end example}.
+
+@example
+@@example
+@@uref@{URL [, link text ]@}
+@@end example
+@end example
 @end itemize
 
 
@@ -583,6 +628,28 @@ only break at spaces, not at hyphens or underscores.  If the block
 contains spaces, use @code{@@w@{@@code@{@dots{}@}@}} or
 @code{@@w@{@@samp@{@dots{}@}@}} to prevent unexpected line breaks.
 
+The Texinfo settings @code{txicodequoteundirected} and
+@code{txicodequotebacktick} are both set in the manuals, so
+backticks (@code{`}) and apostrophes (@code{'}) placed within
+blocks of @code{@@code}, @code{@@example}, or @code{@@verbatim}
+are not converted to left- and right-angled quotes
+(@code{@quoteleft{} @quoteright{}}) as they normally are within
+the text, so the apostrophes in
+@q{@w{@code{@@w@{@@code@{@bs{}relative c''@}@}}}} will display
+correctly.  However, these settings do not affect the PDF output
+for anything within a @code{@@samp} block (even if it includes a
+nested @code{@@code} block), so entering
+@q{@code{@@w@{@@samp@{@bs{}relative c''@}@}}} wrongly produces
+@q{@w{@code{@bs{}relative c@quoteright{}@quoteright{}}}} in PDF.
+Consequently, if you want to use a @code{@@samp@{@dots{}@}} block
+which contains backticks or apostrophes, you should instead use
+@q{@code{@@q@{@@code@{@dots{}@}@}}} (or
+@q{@code{@@q@{@@w@{@@code@{@dots{}@}@}@}}} if the block also
+contains spaces).  Note that backslashes within
+@code{@@q@{@dots{}@}} blocks must be entered as @samp{@@bs@{@}},
+so the example above would be coded as
+@q{@code{@@q@{@@w@{@@code@{@@bs@{@}relative c''@}@}@}}}.
+
 @item
 @code{@@command@{@dots{}@}} --- Use for command-line commands (eg.
 @samp{@@command@{lilypond-book@}}).
@@ -1329,6 +1396,9 @@ motivation and a suitable system, it can be very useful to build at
 least the documentation so that you can check the output yourself and
 more quickly; if you are interested, see @ref{Compiling}.
 
+Before undertaking any large translation work, contributors are
+encouraged to contact the @ref{Meisters, Translation Meister}.
+
 
 @node Which documentation can be translated
 @unnumberedsubsubsec Which documentation can be translated