14

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?

yannisl
  • 117,160
  • Looks related: Is it possible to keep my translation together with original text? – Martin Scharrer Dec 02 '11 at 12:57
  • 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. – yannisl Dec 02 '11 at 13:20
  • Both Charles's or my answer there work with full paragraphs or complete documents. – Martin Scharrer Dec 02 '11 at 13:29
  • 3
    One should distinguish between package documentation and code documentation. You're talking about the latter, aren't you? – egreg Dec 02 '11 at 13:36
  • @egreg Yes, sorry if I was not very clear. For most packages is the same though. – yannisl Dec 02 '11 at 13:47
  • @MartinScharrer I am after how do you handle % Die Schriftfamilie "Gotisch"': % \begin{macrocode} \DeclareFontFamily{LYG}{ygoth}{} \DeclareFontShape{LYG}{ygoth}{m}{n}{% <10><10.95><12><14.4><17.28><20.74><24.88>ygoth}{} % \end{macrocode} % in two languages. I am specifically asking, if there is a solution for .dtx' files. – yannisl Dec 02 '11 at 13:52
  • 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 02 '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 02 '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? – wasteofspace Dec 02 '11 at 15:21
  • @Anon: Because english is the de facto lingua franca. User documentation should be in english if possible, code documentation is best done in a language the author is comfortable with. – Martin Schröder Dec 19 '11 at 22:41
  • 1
    @MartinSchröder english is the de facto lingua franca is fantastic if you think about the words' origins!! – percusse Jan 09 '12 at 13:15

1 Answers1

1

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.
Community
  • 1
juanmah
  • 217