Doc: Issue 3807: Maintaining \version in documentation files

  Add instructions on maintaining the \version string in doc files

diff --git a/Documentation/contributor/doc-work.itexi b/Documentation/contributor/doc-work.itexi
index 680522cbc9a79466fd9a404887e326bc21bace0c..c6d8560c0be772d28d1b4a24e5bc74dff63a362c 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,39 @@ 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 should begin
+with a @code{\version} statement referencing a version of LilyPond
+consistent with the syntax of the contained code.
+
+The @code{\version} statement should be commented out to avoid
+creating problems when building releases with GUB, 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