Re: adding snippets manually

[Carl D. Sorensen]

On 4/17/09 9:16 PM, "Graham Percival" <address@hidden> wrote:

> On Fri, Apr 17, 2009 at 05:38:22PM -0600, Carl D. Sorensen wrote:
>> 
>> In order to build my docs, I copied the file from input/new to input/lsr.
>> 
>> I thought that the doc build process would get files from input/new if they
>> didn't exist in input/lsr.
>> 
>> Can you summarize the process for me?  If I want to add a new snippet to
>> the docs, how should I do it?
> 
> With my trademarked "me-ness", the process is that you read the
> bloody CG 5.
> http://kainhofer.com/~lilypond/Documentation/devel/contrib-guide/Fixing-snippe
> ts-in-LilyPond-sources.html
> http://kainhofer.com/~lilypond/Documentation/devel/contrib-guide/LSR-to-Git.ht
> ml

Perfect answer -- that's much better than rewriting it for me in an email!

> 
> That said, I must admit that CG 5 doesn't go into details of how
> to manually deal with input/new to input/lsr.  The format changes
> slightly.  It's dealt with the python script, but I did it by hand
> a few times for small fixes.

The CG recommends using makelsr.py.  But I thought than only Neil was
authorized to use makelsr.py.

So can I use makelsr.py on my machine, but not add the new lsr files to git?
That doesn't sound particularly good to me.

> 
> I can't remember exactly what it was, but I think it was a matter
> of changing the "tags" line.  Of course, stuff might have changed
> since then (it was a year ago).  Also, I'm not certain that we
> *want* to encourage people to do this by hand.
> 
> I'm also not certain that we want to encourage people to do the
> lsr-to-git change.
> 
> 
> What about stating that new features get an input/regression/
> test, but further snippets wait until the lsr-to-git person looks
> at it?  No wait, that's silly.
> 
> Hmm... I think the best solution would be to allow input/lsr/
> snippets to be exact copies if input/regression/ stuff.  If it
> *is* an exact copy (i.e. misses the tags and whatnot), then the
> build system should put it in an "other" section, which
> lsr-handling people would deal with later.  This way, it still
> gets in the docs, but programmers don't need to deal with the
> snippet suckage.

What I did this time around (and I didn't like it well at all) was just put
a copy in input/new, and copied it to input/lsr.  That gave me a copy of the
title and the texidoc in the snippet, which is *not* nice.  But I think we
need to have some way to get new snippets in the docs pretty quickly.

Thanks,

Carl