Re: CG Information on Snippet Handling

[Neil Puttock]

2009/4/19 Carl D. Sorensen <address@hidden>:

> Perhaps, but I think it's a good idea to actually test how the snippet shows
> up in the docs, because there's documentation, not just LilyPond, in the
> snippet.  Is there another way to do this that's easier than making the
> slight change to the snippet and copying it to input/lsr?

Not really.

> What are the formatting issues when copying snippets into input/lsr?  The
> only thing I've run into is getting the whole header output if you don't put
>  "% begin verbatim" after the header.

I was thinking of the snippets which appeared from input/regression in
chords.itely before John fixed the directory ordering: since they
don't have doctitles, you also get the unformatted snippet name as the
title.

> The doc snippets I write are usually different from the regtests.  The
> headers are different, even if the code isn't any different.

It wasn't a serious suggestion for exactly the reason you give;
naturally LSR snippets should be much more fleshed out.

> So, here's proposal 2:
>
> "If a new snippet created for documentation purposes will compile in
> the current LSR version, the snippet should be added to the LSR, and a
> reference to the snippet should be added to the documentation.
>
> If the new snippet uses new features that are not available in the
> current LSR version, the snippet should be added to input/new and a
> reference should be added to the manual.
>
> Because snippets added to the LSR are not available until an LSR update has
> been done, and snippets added to input/new are not available until
> makelsr.py has been run, the manual reference to new snippets should be
> surrounded by @address@hidden and @address@hidden ignore}.

Running makelsr.py is the LSR update: it generates input/lsr snippets
from LSR and input/new.

> QUESTION:  WHO IS RESPONSIBLE FOR REMOVING THE IGNORE BLOCK?

I think it's best done by whoever's running makelsr.py.

> To have a snippet appear in the documentation before the LSR update and/or
> makelsr.py run have been completed, copy the snippet to input/lsr.  Modify
> the copy of the snippet in input/lsr by adding @code{ % begin verbatim }
> after the header.  Remove the @address@hidden block from
> the documentation, and run make web.  The snippet copy in input/lsr
> will be overwritten when the LSR update has been done or makelsr.py is
> executed by the snippet maintainer."
>
> You know, as I think about it now, I think it's actually easier for me as a
> documentation updater to put the snippet in both places and leave out the
> @ignore block.  I'd rather do that than have to post the snippet, then ask
> for an update, then wait for an update, then update the documentation.

I don't mind what you do, so long as it doesn't break compilation. :)

Regards,
Neil