Re: CG Information on Snippet Handling

[Neil Puttock]

2009/4/18 Carl D. Sorensen <address@hidden>:
>
> I think something like the following needs to go in the CG under
> Documentation Work somewhere -- Probably after TWEAKS in section 3.4.
>
> "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.

It still needs ignoring like input/new snippets until an LSR update's been done.

> If the new snippet uses new features that are not available in the
> current LSR version, the snippet should be added to input/new, a
> reference should be added to the manual, and the reference in the
> manual should be surrounded by @address@hidden and @address@hidden ignore}.

I think this is the simplest option.

> If it is desired to have a snippet with new features appear in the
> documentation, the @address@hidden block should be removed from
> the documentation, and a copy of the snippet should be placed in
> input/lsr, as well as in input/new.  The snippet copy that is in
> input/new should have @code{ % begin verbatim } added after the
> closing brace for the header.  The snippet copy in input/lsr
> will be overwritten when makelsr.py is executed by the
> lsr snippet maintainer."

Seems a waste of time just for the sake of getting a snippet visible
in the docs before makelsr.py has been run.

Another option (though still not ideal since it suffers from the same
formatting issues as pasting snippets verbatim from input/new ->
input/lsr) 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.

Regards,
Neil