lilypond-devel
[Top][All Lists]
Advanced

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

Re: CG Information on Snippet Handling


From: Carl D. Sorensen
Subject: Re: CG Information on Snippet Handling
Date: Sat, 18 Apr 2009 17:15:21 -0600



On 4/18/09 4:55 PM, "Neil Puttock" <address@hidden> wrote:

> 2009/4/18 Carl D. Sorensen <address@hidden>:
>> [Snip original proposal on LSR snippets]
> 
> It still needs ignoring like input/new snippets until an LSR update's been
> done.
> 
>> [Snip original proposal on input/new snippets]
> 
> I think this is the simplest option.
> 
>> [Snip original proposal on manually copying into input/lsr]
> 
> Seems a waste of time just for the sake of getting a snippet visible
> in the docs before makelsr.py has been run.

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?

> 
> Another option (though still not ideal since it suffers from the same
> formatting issues as pasting snippets verbatim from input/new ->
> input/lsr) 

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.

> is to use the same name for the regtest as the new snippet,
> then the docs will automatically pick up the regtest version if
> there's no input/lsr version.

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

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

QUESTION:  WHO IS RESPONSIBLE FOR REMOVING THE IGNORE BLOCK?

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.

Thanks,

Carl





reply via email to

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