Doc: Issue 3807: Maintaining \version in documentation files

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

diff --git a/Documentation/contributor/doc-work.itexi b/Documentation/contributor/doc-work.itexi
index c1dd8adae8a5d63b40191d99c96f142dfdb7b087..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
 
@@ -276,8 +310,6 @@ Level 3 subsections are created with
 @@subsection Foo
 @end example
 
-@itemize
-@item
 Level 4 headings and menus must be preceded by level 3 headings and
 menus, and so on for level 3 and level 2.  If this is not what is
 wanted, please use:
@@ -286,11 +318,9 @@ wanted, please use:
 @@subsubsubheading Foo
 @end example
 
-@item
 Please leave two blank lines above a @code{@@node}; this makes it
 easier to find sections in texinfo.
 
-@item
 Do not use any @code{@@} commands for a @code{@@node}.  They may be
 used for any @code{@@sub...} sections or headings however.
 
@@ -304,7 +334,6 @@ but instead:
 @@subsection @@code@{Foo@} Bar
 @end example
 
-@item
 No punctuation may be used in the node names.  If the heading text
 uses punctuation (in particular, colons and commas) simply leave
 this out of the node name and menu.
@@ -318,17 +347,34 @@ this out of the node name and menu.
 @@subsection Foo: Bar
 @end example
 
-@item
-With the exception of @code{@@} commands and punctuation, the
-section name should match the node name exactly.
+Backslashes must not be used in node names or section headings.
+If the heading text should include a backslash simply leave this
+out of the node name and menu and replace it with @code{@@bs@{@}}
+in the heading text.
+
+@example
+@@menu
+* The set command
+@@end menu
+
+@@node The set command
+@@subsection The @@code@{@@bs@{@}set@} command
+@end example
+
+References to such a node may use the third argument of the
+@code{@@ref} command to display the texually correct heading.
+
+@example
+@@ref@{The set command,,The @@code@{@@bs@{@}set command@}
+@end example
+
+With the exception of @code{@@} commands, @code{\} commands and
+punctuation, the section name should match the node name exactly.
 
-@item
 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
-
 Nodes must be included inside a
 
 @example