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

[dak]

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-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.

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.

https://codereview.appspot.com/51450044/