Dessert #1: DoxyGen < 1.5.x mit UTF-8 nutzen
In diesem kleinem Dessert beschreiben wir, wie man dem automatisierten Dokumentationstool Doxygen UTF-8 beibringt. Dabei beziehen wir uns nur auf die HTML-Ausgabe, HTMLHelp, PDF und RTF wird nicht berücksichtigt.
Wenn man versucht, mit Doxygen eine Dokumentation aus UTF-8 kodierten Dateien zu erstellen, werden leider alle nicht-ASCII Zeichen kryptisch dargestellt. Das Problem tritt auf, da Doxygen die Ausgabe mit einer, in unserem Fall, falschen Zeichenkodierung deklariert. Doxygen weist nämlich UTF-8 Daten als ISO-8859 Daten aus. Dieses Problem tritt nur in Versionen < 1.5.x auf, wie sie derzeit noch in den Standartquellen vom Paketmanager APT zu finden sind. In neueren Versionen kann die Kodierung der Eingabedaten über den Parameter INPUT_ENCODING bestimmt werden.
Wer ungeduldig ist findet die Lösung etwas weiter unten, zunächst folgt etwas Horizonterweiterung.
Das Sie überhaupt irgenntwelche Zeichen sehen und nicht reines Kauderwelsch liegt daran, dass ASCII-Zeichen im ersten Byte des bis zu 4-Byte starken UTF-8 Zeichenformats abgelegt werden. Daher ist die Darstellung von rein aus ASCII-Zeichen bestehenden UTF-8 Daten in ISO kein Problem. Probleme treten erst auf, wenn probiert wird, UTF-8 Zeichen, die keine der 127 ASCII Zeichen sind, in ISO-Zeichensätze, z.B. ISO-8859-1 darzustellen, denn in ISO-8859 ist ein Zeichen immer ein Byte lang und daher sind vier Byte starke UTF-8 Zeichen, als ISO-8859 “gemappt”, 4 Zeichen. Dadurch enstehen mitunter abenteuerliche Phrasen oder einfach nur “Hans”.
Die Lösung
Zunächst einmal generieren Sie Doxygen’s Header-, Footer- und Stylesheetdatei
instantGameInfra1:/mnt/instantGame/www/# doxygen -w html header.html footer.html style.html
Jetzt öffnen Sie die Datei header.html mit einem beliebigen Texteditor, z.B. nano oder vi. Springen Sie in Zeile 2 und ändern Sie im <meta>-Tag den Parameter charset im Attribut content auf UTF-8
<meta http-equiv="Content-Type" content="text/html;charset=UTF-8" />
Nachdem die Datei gespeichert wurde öffnen Sie das Doxyfile ihres Projektes (Wenn Sie noch keins erstellt haben, generieren Sie eins mit doxygen -g). Suchen Sie nach der Zeile HTML_HEADER und geben Sie dort den Pfad zu Ihrer header.html an. Wenn Sie jetzt doxygen aufrufen wird Ihre Dokumentation als UTF-8 markiert und alle Zeichen richtig dargestellt.
Eine andere Methode ist übrings, alle Eingaben mittels iconv in ISO-8859 umzuwandeln. Leider gehen dabei alle Zeichen verloren, die nicht über ISO-8859 dargestellt werden können. Zu Vollständigkeit aber trotzdem eine Erläuterung: Öffnen Sie ihr Doxyfile. Suchen Sie nach der Zeile INPUT_FILE und ändern Sie diese in folgendes:
INPUT_FILTER = "iconv -t iso-8859-15 -f UTF-8 -c"
Am 9. November 2007 um 17:05 Uhr
INPUT_FILTER korrektur
INPUT_FILTER = “iconv -t iso-8859-15 -f UTF-8 -c”
ist meiner Meinung nach falsch herum, es muss laute
I NPUT_FILTER = “iconv -f iso-8859-15 -t UTF-8 -c”
also “from” und “to” ist verwechselt.
mfg
T.Eimers