Re: GDP: examples consistency

[Jean-Charles Malahieude]

Le 29.06.2008 14:27, Graham Percival disait :
> On Sun, 29 Jun 2008 14:10:53 +0200
> Jean-Charles Malahieude wrote:
>
> > First of all I must admit that I am more than a bit lazy, and quite 
> > nitpicking...
>
> Fixing nits is an important part of GDP, so that's fine.
>
> > I would
> > have liked not to encounter twice (or more) the same assertion like:
> >
> > #. Documentation/user/fundamental.itely:1012 (comment)
> > msgid "Set stems, etc, down"
          ^             ^^
> > vs.
> > #. Documentation/user/fundamental.itely:1074 (comment)
> > msgid "set stems, etc down"
          ^             ^
> In this case, I think it's ok.  We simply cannot assume that
> readers will understand material in the LM in the order it's
> presented to them, so a certain amount of re-iteration is ok.
> (This is for the LM only; any such repetition in the NR should be
> fixed.)

The fact is that, due to spelling matter, this same succession of terms
is detected as TWO different strings, even though it is the very same
assertion. This is why I much more appreciate things like:

#. Documentation/user/fundamental.itely:1187 (variable)
#. Documentation/user/fundamental.itely:2497 (variable)
#. Documentation/user/tweaks.itely:3137 (variable)
#. Documentation/user/simultaneous.itely:541 (variable)
msgid "global"
msgstr "global"


> > #. Documentation/user/fundamental.itely:2274 (variable)
> > msgid "sopranoMusic"
> > vs.
> > #. Documentation/user/fundamental.itely:1239 (variable)
> > #. Documentation/user/tweaks.itely:3138 (variable)
> > msgid "SopMusic"
>
> I agree; the second one should be written out fully.  Although I hope
> that you're not translating those strings... I mean, really!  If a
> user can't understand
> sopranoMusic
> then they have no hope of understanding 90% of the standard
> lilypond commands.

That one is just an example...

> > In other words, I would like that arises a "good practice" in 
> > documenting things, which would be that the one who deals with a 
> > specific section adopts a single spelling and/or syntax for each 
> > equivalent assertion.
>
> That would be nice, but checking these details is really hard to
> do in one's own work.  Creating a first public draft of a section
> involves between 10 to 40 hours of work.  I don't want to add more
> to that.

As a matter of fact, I was not checking such details, but reviewing
/Documentation/po/fr.po and wondering about the growing amount of
untranslated strings on the lilypond/translation branch.

> Instead, please point out such issues if you find any in a
> "finished" or "public draft" section.  The finished ones are:
> - LM 2 Tutorial
> - NR 1.1 Pitches
> - NR 1.7 Editorial
>
> Public draft is:
> - NR 1.5 Simultaneous
>
>
> If you haven't done the finished sections yet, you might want to
> stop work on Fundamental and work on those first.  That said,
> I don't know how the French translation team is organized.
>
> Cheers,
> - Graham


I might review these sections over the coming week, and then make a
commit per file if you don't mind.

Cheers
Jean-Charles

(2nd post, for everybody)