Re: Policy decision needed about Documentation/snippets/new

[John Mandereau]

Il giorno mer, 18/07/2012 alle 14.18 +0100, Graham Percival ha scritto:
> 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.

OK.

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

Right.


> I thought your big makelsr patch already did this?

No, in my big patch makesnippets does not read anything in
Documentation/snippets/new.  If it did (i.e. if we went for alternative
2)), then we might want to run convert-ly regularly in
Documentation/snippets/new instead of adding another step in the build
process.

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

I'd rather say the first step is to stop breaking the build repeatedly,
and documenting it in the CG the second.


> 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 just thought that we could run makelsr.py without positional argument
in the doc build process (it just require python and a freshly built
convert-ly).  I'll submit this we Phil and I have finished fiddled with
it so that it really handle all situations; in this case, it would need
to output snippets in Documentation/snippets/out to avoid changing files
tracked by Git, though.

Cheers,
John