Re: What autogenerated documentation to translate

[Jean Abou Samra]

Le 10/01/2022 à 20:08, Jonas Hahnfeld a écrit :
> Am Montag, dem 10.01.2022 um 01:47 +0100 schrieb Jean Abou Samra:
> > Hello,
> >
> > Suppose I submitted a change allowing to translate
> > autogenerated documentation via PO files (likely not
> > this week because I already have syntax highlighting
> > on my plate, but this discussion can already happen now).
> Regardless of what is translated, a quick comment on the *how*: In my
> opinion, this shouldn't be done in the "runtime" translation files in
> po/. There's a separate set of files in Documentation/po/ that are also
> used for translation of the snippets.


Good point.



> > What should we translate?
> >
> > One reason for asking is that the list of Scheme
> > functions
> > (http://lilypond.org/doc/v2.23/Documentation/internals/scheme-functions)
> > is quite large (693 docstrings, as many as context
> > properties and grob properties together) and all very
> > technical, so I don't know if is a good idea to translate
> > it.
> No, if users start programming Scheme, they should be fine with the
> English documentation. In general, I wouldn't translate anything in the
> Internals manual.
>
> > More precisely, for which of the following should
> > translation support be added?
> >
> > - Markup and markup list function docstrings
> > (http://lilypond.org/doc/v2.23/Documentation/notation/text-markup-commands),
> >
> > - Music function docstrings
> > (http://lilypond.org/doc/v2.23/Documentation/notation/available-music-functions),
> These two would be nice because they are user-facing.
>
> > - Type predicates
> > (http://lilypond.org/doc/v2.23/Documentation/notation/predefined-type-predicates),
> Not sure why these are in the NR at all?


I believe it's because you need them in order to
pick predicates for your own syntax functions
(when using define-{music,event,scheme,void}-function).
Too broad a predicate can cause trouble because
it can lead to the argument -2 being taken as a number
when you meant a fingering and similar confusions.



> > - All the stuff in the first three parts of the
> >     Internals Reference: Music definitions, Translation,
> >     Backend (including property docstrings,
> >     music expression & context & engraver & grob interface
> >     docstrings, etc.)
> >
> > - The list of Scheme functions.
> In my opinion, no.


Ok, opinion recorded. I'll wait some more days
to hear others (and as said I won't be working
on this before a few days anyway).

Cheers,
Jean