Doc: CG - remove link to R. Kainhofer's doc builds

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

diff --git a/Documentation/contributor/doc-work.itexi b/Documentation/contributor/doc-work.itexi
index 680522cbc9a79466fd9a404887e326bc21bace0c..70fd22660d1253c438754287d95c7d84e480038e 100644 (file)
--- a/Documentation/contributor/doc-work.itexi
+++ b/Documentation/contributor/doc-work.itexi
@@ -14,6 +14,7 @@ Version Control System (VCS) called git, previously discussed in
 
 @menu
 * Introduction to documentation work::
+* version in documentation files::
 * Documentation suggestions::
 * Texinfo introduction and usage policy::
 * Documentation policy::
@@ -66,6 +67,41 @@ Before undertaking any large documentation work, contributors are
 encouraged to contact the @ref{Meisters, Documentation Meister}.
 
 
+@node version in documentation files
+@section @code{\version} in documentation files
+
+Every documentation file which includes LilyPond code must begin
+with a @code{\version} statement, since the build procedure
+explicitly tests for its presence and will not continue otherwise.
+The @code{\version} statement should reference a version of LilyPond
+consistent with the syntax of the contained code.
+
+Since the @code{\version} statement is not valid Texinfo input it
+must be commented out like this:
+
+@example
+@@c \version "2.19.1"
+@end example
+
+So, if you are adding LilyPond code which is not consistent with the
+current version header, you should
+
+@enumerate
+
+@item
+run convert-ly on the file using the latest version of LilyPond
+(which should, if everybody has done proper maintenance, not change
+anything);
+
+@item
+add the new code;
+
+@item
+modify the version number to match the new code.
+
+@end enumerate
+
+
 @node Documentation suggestions
 @section Documentation suggestions
 
@@ -158,7 +194,7 @@ have the @qq{docs} tag can then be easily added as a
 @emph{selected snippet} in the documentation.  It will also appear
 automatically in the Snippets lists.  See @ref{Introduction to LSR}.
 
-Snippets that @emph{don't} have the @qq{docs} tage will still be
+Snippets that @emph{don't} have the @qq{docs} tag will still be
 searchable and viewable within the LSR, but will be not be included in
 the Snippets list or be able to be included as part of the main
 documentation.
@@ -365,23 +401,10 @@ Most LilyPond examples throughout the documentation can be produced
 with:
 
 @example
-@@lilypond[verbatim,quote,relative=1]
-@end example
-
-or
-
-@example
-@@lilypond[verbatim,quote,relative=2]
+@@lilypond[verbatim,quote]
 @end example
 
-If using any combination of @code{\header@{@}}, @code{\score@{@}} or
-@code{\layout@{@}} in your example, then you must omit the
-@code{relative} variable and either use absolute entry mode or an
-explicit @code{\relative@{@}} construction.
-
-If using @code{\book@{@}} in your example then you must also omit the
-@code{relative} variable and either use absolute entry mode or an
-explicit @code{\relative@{@}} construction.  However, you must also
+If using @code{\book@{@}} in your example then you must also
 include the @code{papersize=X} variable, where @code{X} is a defined
 paper size from within @file{scm/paper.scm}.  This is to avoid the
 default @code{a4} paper size being used and leaving too much unnecessary
@@ -424,8 +447,8 @@ Please avoid using extra spacing either after or within the
 @code{@@lilypond} parameters.
 
 @example
-not:          @@lilypond [verbatim, quote, relative=1]
-but instead:  @@lilypond[verbatim,quote,relative=1]
+not:          @@lilypond [verbatim, quote, fragment]
+but instead:  @@lilypond[verbatim,quote,fragment]
 @end example
 
 @item
@@ -464,7 +487,7 @@ 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
+Try to avoid using @code{#'} or @code{#`} when describing
 context or layout properties outside of an @code{@@example} or @code{@@lilypond}, unless
 the description explicitly requires it.
 
@@ -482,8 +505,8 @@ checks.
 @item
 Tweaks should, if possible, also occur on their own line.
 @example
-not:          \override TextScript #'padding = #3 c1^"hi"
-but instead:  \override TextScript #'padding = #3
+not:          \override TextScript.padding = #3 c1^"hi"
+but instead:  \override TextScript.padding = #3
               c1^"hi"
 @end example
 
@@ -909,6 +932,18 @@ the same format as @code{@@enumerate}.  Do not use
 @node Special characters
 @unnumberedsubsubsec Special characters
 
+@warning{In Texinfo, the backslash is an ordinary character, and
+is entered without escaping (e.g.
+@samp{The@tie{}@@code@{@bs{}foo@}@tie{}command}).  However, within
+double-quoted Scheme and/or LilyPond strings, backslashes
+(including those ending up in Texinfo markup) need to be escaped
+by doubling them:
+@example
+(define (foo x)
+  "The @@code@{@bs{}@bs{}foo@} command..."
+  ...)
+@end example}
+
 @itemize
 @item
 @code{--}, @code{---} --- Create an en dash (--) or an em dash
@@ -1255,15 +1290,6 @@ Note that you have to find yourself the source files to fix
 cross-references in the generated documentation such as the
 Internals Reference; e.g. you can grep scm/ and lily/.
 
-@c temporary?  how long will kainhofer be used?  -gp
-Also of interest may be the linkdoc checks on kainhofer.com.  Be
-warned that these docs are not completely rebuilt every day, so it
-might not accurately reflect the current state of the docs.
-
-@example
-@uref{http://kainhofer.com/~lilypond/linkdoc/}
-@end example
-
 
 @node General writing
 @subsection General writing
@@ -1445,7 +1471,7 @@ good example of this.
 On the other side of this,
 
 @example
-\override Score.Hairpin #'after-line-breaking = ##t
+\override Score.Hairpin.after-line-breaking = ##t
 @end example
 
 clearly belongs in LSR.
@@ -1829,7 +1855,7 @@ will be handled by someone who will translate it to English and send it
 on bug-lilypond or add an issue in the tracker, then translate back the
 reply from developers.
 
-@item @rweb{Help us}: this page should be translated very freely,
+@item @rcontrib{Help us}: this page should be translated very freely,
 and possibly not at all: ask help for contributing to LilyPond for tasks
 that LilyPond community in your language is able and going to handle.
 @end itemize