Re: Snippets in doc compile different from stand-alone

[Carl Sorensen]

On 7/15/09 9:48 AM, "John Mandereau" <address@hidden> wrote:

> Le mardi 14 juillet 2009 à 16:21 -0600, Carl Sorensen a écrit :
>> Hmm -- I read through the CG and missed it.  Now that I know what I'm
>> looking for, I see where it is.  I'll add something to the CG.
> 
> Thanks. The general problem when I write instructions in the CG (besides
> the fact that I still haven't updated it enough) is that I have in mind
> the design of the translation infrastructure, that AFAIK is only known
> by Jan, me, and probably a little by Han-Wen and Reinhold. The more I
> think about it, the more I find I should write a short paper and/or CG
> section that explains the general design of the docs translations
> integration, so we can avoid formalizing too many procedure details
> related to translations into the CG.

I tried running 

make ISOLANG=fr snippet-update

from Documentation/.  It ran, but most of the files were not able to be
updated because they had a different snippet count.  So at the present time,
make snippet-update is not particularly useful in terms of updating
snippets; the work will need to be done largely by hand.

> 
> 
>> But if I've changed syntax, and the translated manuals will no longer work
>> properly, then I break compilation if I push a patch.
>> 
>> So in the case of a syntax change that needs a NOT_SMART convert-ly rule, we
>> should have some procedure in place to avoid future occurences of this
>> problem, it seems to me.
> 
> The procedure that used to be applied by Jan, Han-Wen and other
> contributors was to apply syntax changes in snippets
> (@lilypond/@lilypondfile) to all languages without asking anything, or
> (I can't remember whether they have already done so) commenting out or
> remove broken snippets in translations. The former is the most sensible
> thing to do IMHO.

So, just to make sure I'm clear on this, I'd like to propose the following
for addition to the CG:

When a snippet is changed or deleted from the english documentation, the
same change (or deletion) should be applied to all translated versions of
the documentation.

However, when text is changed, added, or removed from the english
documentation, no changes should be made to the translated versions of the
documentation.


Is this correct?

Thanks,

Carl