GDP: translations and code comments

[Graham Percival]

On Wed, 16 Apr 2008 09:35:53 +0200
"Francisco Vila" <address@hidden> wrote:

> 2008/4/16, Graham Percival <address@hidden>:
> > Difficult to do without using lots of @code{propertyNames} in the
> >  main text.  In this case, I'd rather keep the explanation in the
> >  code.
> 
> Regarding to in-code explanations, it must be noted that they are
> untranslatable. I know that it is possible to customize the lilypond
> blocks but it is stated in README that they should only be used for
> very special cases; these special cases are more and more often needed
> if more and more explanations go into the code itself. So I plan in a
> second phase of the translation to translate the code of all lilypond
> blocks that have comments and other texts inside, as well.

Mao.  I wish somebody had mentioned this back in Jan when I was
seeking comments on Pitches.

Ok, let's consider a new policy: no comments in NR 1+2.  I've
updated pitches.itely and editorial.itely accordingly.

At the moment, I can't think of any feature for which I can
honestly say that it needs comments to document it.  There are
plenty of examples that would need comments to clarify them, but
it strikes me that those examples should be clarified first.  If
we use good small examples for everything, it should be clear
without comments.

This kind-of falls down in the LM, of course.  Picking a random
portion of the docs, I looked at LM 3.2.2 Explicitly instantiating
voices.  I really can't argue that the final two examples would be
better off without comments.

So I guess that if you want to translate everything, you'll *have*
to translate a large number of lilypond code as well.  This
strikes me as an inefficient use of resources -- both in
translating time, but also simply in computer resources in
building identical lilypond snippets which only differ in the
language of their comments.  But I can't see a way around this.
:|


Cheers,
- Graham