Most classes and packages on ctan, offer a .dtx file, which when processed will automatically produce a user manual. In most cases such classes use the author's mother language. As for example yfonts is written in German. In my opinion any such classes and packages they should offer documentation at least in English as well as a second language. This can be done by either the author or one of the many volunteers.

Is there a convention or a recommended convention for doing so? Can one give an example, how to go about for example extending the yfonts documentation to English? What about if a third language is introduced, cramming everything into the .dtx file would render it unreadable. Using babel and Beamer's translate, would be tedious and prone to errors when the primary author makes an update. Do we need an extension to docstrip for this?

  • 1
    @MartinScharrer They are actually totally unrelated, if you read both questions carefully:). The link you point to had a one macro answer, where I am looking to find a solution to the whole text of a package, i.e., all the stuff that end up in the manual. Dec 2 '11 at 13:20
  • 3
    One should distinguish between package documentation and code documentation. You're talking about the latter, aren't you?
    – egreg
    Dec 2 '11 at 13:36
  • 2
    @YiannisLazarides I'd say code should only be documented in one language. A good package has user documentation for 'everyone else', and the code comments are really for the developers. It's not realistic to write those comments in multiple languages, but more importantly its encouraging the idea that users should be reading these comments: they should not need to. (This applies even to 'programming support' packages, where it's still important to have 'user' documentation, but for user programmers.)
    – Joseph Wright
    Dec 2 '11 at 13:56
  • 1
    @YiannisLazarides: Ok, I was thinking you are talking about the user documentation part, not the code documentation. IMHO, there is no reason at all to have the code documentation in any other language than English, besides the one that the author isn't able to speak/write English. I also highly disagree that "for most pages is the same". There are a thankfully only a few that mix the user and code documentation, which IMHO means they don't have a proper user documentation! Both should be separated.
    – Martin Scharrer
    Dec 2 '11 at 14:14
  • 4
    there seems to be an assumption that anyone can write in english; this is fine for me, but not so for many ctan contributors. why is it appropriate to require people to write in a language they can hardly understand? if i were required to document my packages in russian, i would have taken years longer to develop my packages. why should a russian-speaker be expected to document in english? Dec 2 '11 at 15:21

There is no a straightforward way to do it. But you can do in two steps:

  1. Convert the document .dtx to .tex as described here.
  2. Use po4a for translating text chains and create a new .tex document in another language.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.