Re: CG Information on Snippet Handling

[Carl D. Sorensen]

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

> 2009/4/19 Carl D. Sorensen <address@hidden>:
> 
> 
>> 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.

Yes.  I agree that it's really not optimal to have regression snippets show
up in the docs.

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

When you run makelsr.py, do you get a message about new snippets that have
been added, so you know snippet names to search the documentation for?

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

OK, so how about this for proposal 3 for something to go into the CG:


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

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 }
immediately after the header.  Remove the @address@hidden block from
the documentation, and run make web.  Be sure that make web runs
successfully before submitting a patch, to prevent breaking compilation.

The handmade snippet copy in input/lsr will be overwritten by an
automatically-generated copy when makelsr.py is executed by the snippet
maintainer."


Thanks,

Carl