[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: CG Information on Snippet Handling
From: |
Neil Puttock |
Subject: |
Re: CG Information on Snippet Handling |
Date: |
Sun, 19 Apr 2009 00:45:40 +0100 |
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
- CG Information on Snippet Handling, Carl D. Sorensen, 2009/04/18
- Re: CG Information on Snippet Handling, Neil Puttock, 2009/04/18
- Re: CG Information on Snippet Handling, John Mandereau, 2009/04/20
- Re: CG Information on Snippet Handling, John Mandereau, 2009/04/24
- Re: CG Information on Snippet Handling, Graham Percival, 2009/04/24
- Re: CG Information on Snippet Handling, Carl D. Sorensen, 2009/04/24
- Re: CG Information on Snippet Handling, Graham Percival, 2009/04/24