Doc: Issue 3807: Maintaining \version in documentation files

Doc: Issue 3807: Maintaining \version in documentation files

  Add instructions on maintaining the \version string in doc files

[dak, 2014-01-19 12:40:55]

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

https://codereview.appspot.com/51450044/diff/1/Documentation/contributor/doc-...
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.

[Trevor Daniels, 2014-01-19 13:02:36]

On 2014/01/19 12:40:55, dak wrote:
>
https://codereview.appspot.com/51450044/diff/1/Documentation/contributor/doc-...
> File Documentation/contributor/doc-work.itexi (right):
> 
>
https://codereview.appspot.com/51450044/diff/1/Documentation/contributor/doc-...
> 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

[dak, 2014-01-19 13:27:22]

On 2014/01/19 13:02:36, Trevor Daniels wrote:
> On 2014/01/19 12:40:55, dak wrote:
> >
>
https://codereview.appspot.com/51450044/diff/1/Documentation/contributor/doc-...
> > File Documentation/contributor/doc-work.itexi (right):
> > 
> >
>
https://codereview.appspot.com/51450044/diff/1/Documentation/contributor/doc-...
> > 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.

Well, no idea about what should be in this section.  Feel free to filter it to
something making sense.

What is utterly wrong is "The @code{\version} statement should be commented out
to avoid creating problems when building releases with GUB": the @code{\version}
statement needs to be _present_ in order to successfully build a release.  Not
because it would "create problems", but because the build procedure _explicitly_
checks for its presence and refuses to continue otherwise.

The \version statement needs to be _commented_ _out_ in order not to confuse
Texinfo and/or LilyPond (when it is merely an _include_ file).

So the reasoning is quite off.

[Trevor Daniels, 2017-01-28 22:06:08]

Pushed to Staging as
[r643e6b2322f7091cde05b7add4903634c661cf0e]
[r2a1dd5d955ab07001ce7e6835966e741bbb99f4a]

Closing ...