Re: Doc: Issue 3807: Maintaining \version in documentation files (issue 51450044)

[tdanielsmusic]

Reviewers: dak,

Message:
On 2014/01/19 12:40:55, dak wrote:

https://codereview.appspot.com/51450044/diff/1/Documentation/contributor/doc-work.itexi
> File Documentation/contributor/doc-work.itexi (right):


https://codereview.appspot.com/51450044/diff/1/Documentation/contributor/doc-work.itexi#newcode77
> Documentation/contributor/doc-work.itexi:77: The @code{\version}
statement
> should be commented out to avoid
> Sigh, I just can't keep up with reviewing stuff.  This statement is
utterly
> wrong.

> It's more like
> A @code{\version} statement is required in all Texinfo documentation
files
> (ending with @samp{.tely} or @samp{.itely}) as well as LilyPond input
files
> (ending with @samp{.ly} or @samp{.ily}) in order to keep track of the
current
> syntax.  Its presence is required for building a release.

> Since the @code{\version} statement is not valid or reasonable input
outside of
> standalone LilyPond files, it will more often than not commented out.
In
> Texinfo, this will be done using
> @example
> @@c \version "2.19.1"
> @end example

> @code{convert-ly} and GUB will recognize the statement even if
commented out.

I'll change it, but why is it utterly wrong?  It is in the section
dealing solely with documentation files, namely those with .itely,
.itexi
and .tely extenders?  There's no point in mentioning the others here.

Trevor


Description:
Doc: Issue 3807: Maintaining \version in documentation files

  Add instructions on maintaining the \version string in doc files

Please review this at https://codereview.appspot.com/51450044/

Affected files (+34, -0 lines):
  M Documentation/contributor/doc-work.itexi


Index: Documentation/contributor/doc-work.itexi
diff --git a/Documentation/contributor/doc-work.itexi  
b/Documentation/contributor/doc-work.itexi
index  
680522cbc9a79466fd9a404887e326bc21bace0c..c6d8560c0be772d28d1b4a24e5bc74dff63a362c  
100644
--- 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}.


address@hidden version in documentation files
address@hidden @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:
+
address@hidden
+%c \version "2.19.1"
address@hidden example
+
+So, if you are adding LilyPond code which is not consistent with the
+current version header, you should
+
address@hidden
+
address@hidden
+run convert-ly on the file using the latest version of LilyPond
+(which should, if everybody has done proper maintenance, not change
+anything);
+
address@hidden
+add the new code;
+
address@hidden
+modify the version number to match the new code.
+
address@hidden enumerate
+
+
 @node Documentation suggestions
 @section Documentation suggestions