2009/4/19 Carl D. Sorensen <c_soren...@byu.edu>:
> 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 @cod...@ignore} and @cod...@end 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 @cod...@ignore} 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
_______________________________________________
lilypond-devel mailing list
lilypond-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-devel
