Re: Policy decision needed about Documentation/snippets/new

[Phil Holmes]

----- Original Message ----- 
From: "Graham Percival" <address@hidden>
To: "John Mandereau" <address@hidden>
Cc: "lilypond-devel" <address@hidden>
Sent: Wednesday, July 18, 2012 2:18 PM
Subject: Re: Policy decision needed about Documentation/snippets/new


> On Wed, Jul 18, 2012 at 03:08:55PM +0200, John Mandereau wrote:
> > Note that in the case you change a single or a couple of snippets in
> > Documentation/snippets/new and don't want to update everything by
> > downloading and unpacking a tarball from LSR website, there are
> > currently contradictory instructions:
> > * one page tells to run makelsr.py
> > http://lilypond.org/doc/v2.15/Documentation/contributor/adding-and-editing-snippets
>
> This is the correct option.

Agreed.

> > 1) Current behaviour (broken and not well documented, but can be easily
> > fixed)
> >
> > .ly files in Documentation/snippets/new are not used directly by
> > documentation build, they are run through makelsr.py, which adds a "Do
> > not edit" comment and convert-ly the file into Documentation/snippets.
> > Any fix or change to Documentation/snippets/new that isn't concerned
> > with syntax changes could be done by making the change simultaneously in
> > Documentation/snippets and Documentation/snippets/new, but we wouldn't
> > document it and require instead to run makelsr.py without arguments
> > after a fresh "make" (without "make doc") and with LILYPOND_BUILD_DIR
> > set correctly.
>
> Yes, this is the correct option [for now].
>
> > The advantage of this alternative is that the only changes to be made
> > are a few lines in makelsr.py and the CG.  Its disadvantage is that
> > developers may edit just Documentation/snippets/new, thus leaving
> > changes untested for a few days or weeks; for example, IIUC
> > 4ab6e4df934e57c51dbbdbf2c209273c6cb5b888 (May 9 2012)
> > was not used in doc build until 9fe18536fe333c167fe1bd87f76a30b20f603dd0
> > (June 19 2012), and missed release 2.15.39. There are other older
> > examples of this.
>
> The LSR editor should be running makelsr.py at least once a week.
> A high-achiever could even work it into the release instructions
> for added safety, although that of course may require a few rounds
> before it's completely correct (because I refuse to let the
> release checklist to get out-of-date with the "reality on the
> ground" like other parts of the CG).

I certainly think this is the best option until we've let the new system get 
shaken down - i.e. minimum other changes.

I agree with your once a week.  I'll try to keep to that schedule from now.

> > 2) Other behaviour

I think this is really "A suggested alternative" ?

> > In doc build, makesnippets runs in both Documentation/snippets and
> > Documentation/snippets/out, and lilypond-book looks for .ly files in
> > Documentation/snippets/new/out before Documentation/snippets/out.
> > Snippets in Documentation/snippets/new should no longer be
> > copied/handled by makelsr.py to Documentation/snippets.
>
> I thought your big makelsr patch already did this?  Anyway, I'm
> not opposed to it, but I think the first step is to ensure that
> the CG presents a working set of steps.
>
> For that reason, I think we should document the first option, and
> if/when the build supports this alternate behaviour, change the CG
> then.

I think the idea of building snippet documentation so that snippets in new 
take priority in the build from snippets in snippets is a good suggestion. 
I do think it would be better to hold off for a bit - as I said, let the new 
system shake down a bit.

--
Phil Holmes