[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Policy decision needed about Documentation/snippets/new

From: Phil Holmes
Subject: Re: Policy decision needed about Documentation/snippets/new
Date: Wed, 18 Jul 2012 14:32:11 +0100

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

This is the correct option.


1) Current behaviour (broken and not well documented, but can be easily

.ly files in Documentation/snippets/new are not used directly by
documentation build, they are run through, 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 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 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 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 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

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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]