Re: Documentation translation: first patch

[John Mandereau]

Han-Wen Nienhuys wrote:
> Jan Nieuwenhuizen escreveu:
> > No idea.  I also only see commits on master on my rss feed?

For branches other than master, I update my local copy, then I use gitk
to track the changes. Thanks to it I could check in 5 minutes that the
French tutorial.itely was almost up to date.

> Yes, IIRC this is fixed in a recent git update. hopefully, savannah
> will update soon.

Ah, these are good news!



> > Clever/ugly things could be: do re.sub only on part until some footer
> > mark, or add some sort of do-not-strip-me attribute to an url...
> 
> Quickest hack I can think of:
> 
> enclose the menu in <!--language_selection>
> 
> (or probable <div id="langselect"></div id="langselect">) and use that
> to make the stripper ignore the language menu.
> 
> Alternatively, we could move the language menu entirely out of
> add-html-footer, and provide (en,fr) links in
> Documentation/index.html.in
> 
> I think most people use the web interface to the docs anyway.

Yes, certainly. There are also some people who want to print the docs;
e.g. a French user recently reported on lilypond-user-fr that he tried
to print the HTML tutorial translation, which (not very surprisingly)
led to a poor result. A French PDF of the user manual would be great,
but we have more important issues to fix before that.


> > We'd still have to build the .html's twice.
> 
> Why?

I'm not sure what Jan means, but instead of just a CONTENT_NEGOTIATION
switch, there could be several simultaneous docs targets,  as I
suggested in
http://lists.gnu.org/archive/html/lilypond-devel/2006-11/msg00206.html 

I don't mean the html docs should be builded twice from the Texinfo
sources, rather than the WWW-post makefile target would create one or
several trees, depending on a FINAL_TARGETS variable. There should be at
least two possible targets, one for the online flavor, and the other for
the offline flavor.

For example,

make FINAL_TARGETS='online offline' web

would build both targets, and FINAL_TARGETS could default to 'offline'
as most builders don't care about the online flavor.

I guess this could be done by calling add-html-footer.py after copying
the docs to /out-www/web-root, and add-html-footer could for each HTML
input file write each flavor to a dedicated tree
(/out-www/web-root-online, /out-www/web-root-offline).

I hope this plan shouldn't involve ugly/clever hacks. How does it sound?


Besides that, I have polished the tutorial, translated the tutorial node
names and will push everything when I'll have found all translators
(this evening, if everything is ok).

I'm going to create a "DOCUMENTATION TRANSLATORS" section in THANKS, and
add translators to AUTHORS.texi, as even the translation polishers (like
me) have spent at least as much time as writing one or two hundred lines
of code (tutorial.itely is 1400 lines long). In fact, it took me more
than 8 hours in the past days to check consistence with English version,
spelling, grammar, style and technical vocabulary.

Speaking of, I have some questions about style. I think I understand the
reasons leading to most of the rules in README.txt, except one.
It sounds well to me that most snippets continue the sentence, as if
music or code were just words; however, I feel there needs to be a colon
in much more places in French translation than in the original, because
I feel the snippet is another part of the sentence there.

We've added little bits specific to French users, about localization of
messages and French note pitches. They are enclosed between '@c DIV
specific' and '@c END DIV' lines (DIV like divergence), so everyone can
track them. In the same way, parts of the docs French users/translators
want to improve, modify or create will be marked respectively with 'DIV
different' and 'DIV new'.


About fresh news from the translators, Ludovic Sardain has translated
introduction.itely. IMHO we should deal with the tutorial well first,
then merge fr-doc into stable/2.10. Then I'll commit new translated user
manual stuff directly to stable/2.10 when it has been enough polished on
address@hidden , so you won't have to wait for the translators
for releases.



-- 
John Mandereau <address@hidden>