Multilingual documentation

[lucarabistouille]

I would like to translate gabc documentation in French. Should I directly translate html pages of the doc or use a specific format for this? For example putting it on a readthedocs website?

Thank you and a joyful feast of Pentecost!

[rpspringuel]

Back when we were hosted on gna.org, we had multi-lingual support, but everything other than English tended to be way behind so that it made sense to simply pull translations rather than leave up outdated information. Eventually we just pulled all the translations when migrating to GitHub.

I'm not opposed to translations, but given that history, we need some way of keeping them up to date. If you're volunteering to translate the docs to French, would you also be willing to keep those translations up to date (not necessarily indefinitely, but at least for a while)?

Further, I'm inclined to favor a solution which keeps our content here in this repository, as that would make it easies to pull a translation when ongoing support for it ceases. I'm not sure how we would do that without some major restructuring of the website to make use of Jekyll or some other solution (which 5 minutes of Googling have yet to reveal). Of course, as you'd be the one doing the translation, I'd like to hear from you what would make your life the easiest so that you'd be able to stay on top of things.

Finally, I should warn you that our online documentation is horribly incomplete at the moment. Our most extensive and complete documentation is in GregorioRef.pdf and GregorioNabcRef.pdf. Further, even those documents need some work (particularly in the gabc section of GregorioRef.pdf). Before embarking on a translation project, it might be better to get our documentation house in order so that everything is up to date and in sync. Otherwise you might translate something only to find it changed within a very short time. Would you be willing to help out get our documentation house in order as part of doing the translation?

[lucarabistouille]

Thank you for the very complete answer.

1/ About the problem of keeping everything up-to-date

It would perhaps be possible to have a version-controlled documentation such as in many opensource projects. Perhaps in some new repository only dedicated to this part of the project?

One example is gnuplot which provides translation for older version than the current one: Gnuplot.

PS : By the way, I could try to keep the French doc up-to-date.

2/ About how to do it

Perhaps, would it be possible to consider having documentation files in an easily convertible format such as markdown + pandoc to then convert it in pdf or html?

[rpspringuel]

About the problem of keeping everything up-to-date

We've already got 4 to 6 repositories (depending on how you count them) related to this project:

1. gregorio-project/gregorio : The main project repository
2. gregorio-project/gregorio-test : The repository containing all the tests we use to make sure changes aren't breaking anything unexpected
3. gregorio-project/gregorio-project.github.io : This repository where the website is located
4. gregorio-project/gregorio.wiki : Not really a separate repository (though it can be cloned as one) but the main project's wiki pages where we store developer specific information
5. gregorio-project/hyphen-la : The repostiory for latin hyphenation rules and tools
6. gregoria4o : a private developer repository (not on GitHub) for the purpose of converting Gregoria (a commercial font for typesetting gregorian chant) for use with Gregorio (with the permission of the font designer)[^1]

I would be opposed to adding yet another repository (as it might get "lost" and become "out of sight, out of mind") and would suggest that this repository is the most logical place for user documentation to live. The trick would simply be to figure out how to do so in as straight forward a manner as possible.

About how to do it

I like the idea (indeed, gregorio-project/gregorio#1135 was created with that sort of brain storm in mind), but would need to see a working sample before committing to it. Part of the reason our most complete documentation is written in LaTeX (and is solely for the GregorioTeX side of things) is because that was what I was most comfortable with when I undertook gregorio-project/gregorio#33 in which the basis of our current documentation system was started. Since then we've been pretty good about keeping the documentation up to date (at least for the TeX part) as we make changes, in part because the documentation source is in the main repository and thus we can see that each change has been properly documented as part of the PR for said change. Changing over the documentation to some new system is going to require a whole bunch of work, so if you can show us a sample file set/workflow that allows us to have up to date docs in both pdf and html format it would definitely help.

[^1] This project hasn't seen any action since 2015, and so may be dead.

[lucarabistouille]

Well perhaps being not too much ambitious is indeed a better idea!

To begin with, just translating the « tutorial » parts for beginners could certainly be a better idea? Technically quite easy, as I would just translate the html pages in French and add some links in the Tutorials main page.