[Doxygen-develop] Translators revisited (searching for volunteers)

[Petr P. <Pr...@sk...>]

(Posted to doxygen-develop, copied to doxygen-users.)

Translators revisited? Again? (Dust covers the old doc.)

Do you think that the things below should have
some wiki page (for discussion)?

This is related to possible future implementation
of the translation of Doxygen output to the
supported human languages. The below mentioned
document was last touched in August 2001 (when
Doxygen's XML output support just begun or even
was not there -- I am not sure). Some experimental=20
work was also done in that time to replace the code=20
of the translator classes by string templates that could
possibly be placed outside the doxygen executable,
in text files (entity definitions, or so).=20

The full doxygenable source and the html of=20
the document is available at
http://www.skil.cz/doxygen/TranslatorsRevisited.zip
(Note that it was done more than 3 years earlier,=20
with older Doxygen.)

Some experimental C++ sources that show how the
things could be done are available at=20
http://www.skil.cz/doxygen/Conversion.zip
It contains also doxy.exe (Windows) and the
generated results from the translator_xx.h files
(as mentioned in the document).

The later http://www.skil.cz/doxygen/Conversion2.zip
contains a source that is a bit newer but without
the things around. I believe it was intended to
use with the slightly changed doxygen sources.

The http://www.skil.cz/doxygen/dox_revisited.zip
contains some sources that show how the changes
could be incorporated into the doxygen sources.
Some tricks mentioned in the "Translators revisited".

If you are willing to help, please, feel free to
contact me (or Dimitri) to discuss the details.


Some motivation for the changes
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D

Recently, Johann 'Myrkraverk' Oskarsson asked some
details about translating some documentation to
another human language. After some clarification
he wrote:
 =20
   Ideally, I'd like a system, similar to Qts tr()
   system, where doxygen would generate
   translation files, and then use them to
   generate the docs.

   I can imagine this could work with the
   experimental XML output, if that can be used to
   generate the rest of the docs (or if that
   feature is trivial to add).


Possibly, some of the needs could be solved using
the approach. It would also be nice to get some
developer that knows XML and also the XML
generated by Doxygen.

The following text is the excerpt from the
"Translators revisited" old document:

    Motivation
   =20
    Language support is now implemented via classes
    based on the abstract class Translator. The main
    reason is that, generally, it is difficult to
    produce nicely readable sentences from fragments
    of the chosen language.
   =20
    It is impossible to generalize the process of
    gluing the fragments together independently on the
    language. It's because the language rules cannot
    be generally algoritmized. Often, the whole
    sentences must be generated. It was found easier
    to do it programmatically, because the language
    maintainer can modify the sentence according to
    the passed arguments.
   =20
    Basically, the generated sequences may contain
    document-related generated parts, e.g. single
    identifiers or lists of identifiers. The generated
    sentences and fragments may be modified via
    argument values like first_capital, plural, etc.
   =20
    On the other hand, it would be much easier for the
    language maintainers or even for end users to
    maintain the language via editing text files,
    without need to recompile whole doxygen.
   =20
    The idea is based on implementing a mechanism that
    will use templates for whole sentences. The
    fundamental question is How?

(Detailed questions, some answers, and steps=20
planned to implement everything can be found=20
inside the document.)

Regards,=20
  Petr

--=20
Petr Prikryl (prikrylp at skil dot cz)=20