use the new flexcat's source description file

[AROS.git] / tools / flexcat / doc / FlexCat_german.texinfo

\input amigatexinfo
\input texinfo
@c %**start of header
@setfilename FlexCat_deutsch.guide
@settitle FlexCat @value{VERSION}    Dokumentation
@setchapternewpage off

@c
@c  FlexCat:                The flexible catalog generator          V1.7
@c  Copyright (C)   1993    Jochen Wiedmann
@c
@c  This program is free software; you can redistribute it and/or modify
@c  it under the terms of the GNU General Public License as published by
@c  the Free Software Foundation; either version 2 of the License, or
@c  (at your option) any later version.
@c
@c  This program is distributed in the hope that it will be useful,
@c  but WITHOUT ANY WARRANTY; without even the implied warranty of
@c  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@c  GNU General Public License for more details.
@c
@c  You should have received a copy of the GNU General Public License
@c  along with this program; if not, write to the Free Software
@c  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
@c
@c
@c  This file contains the german documentation.
@c
@c  Computer:   Amiga 1200                  Compiler:   DICE V2.07.54 (3.0)
@c
@c  Autor:      Jochen Wiedmann
@c              Am Eisteich 9
@c        72555 Metzingen
@c              Tel. 07123 / 14881
@c              Internet: wiedmann@uni-tuebingen.de
@c

@set VERSION 1.7
@set xrefstring siehe
@set Xrefstring Siehe
@set Chapterstring Abschnitt
@set Sectionstring Abschnitt
@set sectionstring Abschnitt
@set pagestring Seite
@set Contentsstring Inhaltsverzeichnis
@iftex
@afourpaper
@parskip=0.75em
@end iftex
@c %**end of header


@titlepage

@title{FlexCat}
@subtitle{Der flexible Kataloggenerator}
@subtitle{}
@subtitle{Version @value{VERSION}}
@author Jochen Wiedmann
@vskip 0pt plus 1filll
@tex
@halign{@hfil#&#@hfil@cr
Copyright @copyright 1993 & Jochen Wiedmann@cr
           & Am Eisteich 9@cr
          72555 & Metzingen (Deutschland)@cr
           & Tel. 07123 / 14881@cr
           & Internet: wiedmann@@uni-tuebingen.de@cr
}
@end tex

Diese Dokumentation sowie das gesamte Programmpaket dürfen im Rahmen der
``GNU General Public License''
kopiert, verändert und weitergegeben werden solange diese
Copyright-Notiz und diese Erlaubnis unverändert auf allen Kopien enthalten
ist und die
``GNU General Public License'' der Free Software Foundation (in der Datei
@code{COPYING}) mitkopiert und weitergegeben wird.

@ignore
Permission is granted to process this file by TeX and print the results,
provided the printed document carries a copying permission notice identical to
this one except for the removal of this paragraph (this paragraph not being
relevant to the printed manual).
@end ignore

Es wird @strong{keine} Garantie gegeben, daß die Programme, die in dieser
Dokumentation beschrieben werden, 100%ig zuverlässig sind. Sie benutzen
diese Programme auf eigene Gefahr. Der Autor kann auf @strong{keinen} Fall
für irgendwelche Schäden verantwortlich gemacht werden, die durch die
Anwendung dieser Programme entstehen.
@end titlepage
@iftex
@headings double
@end iftex

@ifinfo
@node Top
@top FlexCat V@value{VERSION} Dokumentation
Diese Datei beschreibt den Umgang mit FlexCat V@value{VERSION}, einem
Programm zur Erzeugung von Catalogs und dem sie verwendenden Quelltext.
FlexCat arbeitet wie @code{CatComp} oder @code{KitCat}, kann aber praktisch
beliebigen Quelltext erzeugen. Dies funktioniert durch sogenannte
@code{Source-description-Dateien}, die gewissermaßen eine Vorlage für den
zu erzeugenden Quelltext darstellen. Sie können mit einem Editor bearbeitet
und verändert werden und dadurch hoffentlich an beliebige Programmiersprachen
und Bedürfnisse angepaßt werden.

@menu
Allgemeines:

* Copyright::           Copyrights, (Nicht)-Garantie
* Übersicht:Uebersicht. Was ist FlexCat?
* Installation::        Wie kriege ich das Ding zum Laufen?

Arbeit mit dem Programm:

* Programmstart::       Aufruf des Programms
* Catalog description:: Katalogbeschreibungsdateien (@key{.cd}-Dateien)
* Catalog translation:: Katalogübersetzungsdateien (@key{.ct}-Dateien)
* Source description::  Quelltextbeschreibungsdateien (@key{.sd}-Dateien)
* Benutzung::           Einbau des erzeugten Quelltextes in eigene Programme

Überflüssiges:

* Zukunft::             Weiterentwicklung des Programms
* Danksagungen::        Was ich schon lange mal sagen wollte@dots{}
* Index::               Wo das steht, was garantiert nicht gesucht wird
@end menu
@end ifinfo





@ifinfo
@node Copyright
@chapter Copyright und andere rechtliche Dinge
@cindex Copyright
@cindex Distribution
@cindex Rechtliche Dinge
@cindex Genehmigungen
@cindex Verbote
@cindex Autor
@cindex Adresse
@cindex Internet
@cindex Mail
@example
Copyright @copyright{} 1993     Jochen Wiedmann
                        Am Eisteich 9
                  72555 Metzingen (Deutschland)
                        Tel. 07123 / 14881
                        Internet: wiedmann@@uni-tuebingen.de
@end example

Diese Dokumentation sowie das gesamte Programmpaket dürfen im Rahmen der
``GNU General Public License''
kopiert, verändert und weitergegeben werden solange diese
Copyright-Notiz und diese Erlaubnis unverändert auf allen Kopien enthalten
ist und die
``GNU General Public License'' der Free Software Foundation (in der Datei
@code{COPYING}) mitkopiert und weitergegeben wird.

@ignore
Permission is granted to process this file by TeX and print the results,
provided the printed document carries a copying permission notice identical to
this one except for the removal of this paragraph (this paragraph not being
relevant to the printed manual).
@end ignore

Es wird keine Garantie gegeben, daß die Programme, die in dieser Dokumentation
beschrieben werden, 100%ig zuverlässig sind. Sie benutzen diese Programme auf
eigene Gefahr. Der Autor kann auf @strong{keinen} Fall für irgendwelche
Schäden verantwortlich gemacht werden, die durch die Anwendung dieser
Programme entstehen.
@end ifinfo



@node Uebersicht
@chapter Übersicht
@cindex Übersicht
@cindex Compiler
@cindex Programmiersprache
Seit der Workbench 2.1 bietet der Amiga ein sehr schönes System an, mit
dem Programme in verschiedenen, praktisch beliebigen Sprachen benutzt
werden können: Die @code{locale.library}. (Man nennt diesen Vorgang
@code{Lokalisierung}, daher der Name.)

Die Idee ist eigentlich recht simpel: Man wählt eine Sprache, meist die
englische aus und schreibt sein Programm ganz normal, abgesehen davon,
daß Strings nicht mehr direkt eingegeben werden, sondern über einen
Funktionsaufruf im Programm verwendet werden. Durch einen weiteren
Funktionsaufruf zu Beginn des Programms erhält der Benutzer nun die
Möglichkeit, anstelle der vorgegebenen Strings andere zu wählen, die in
einer externen Datei, einem sogenannten @code{Katalog} enthalten sind.

Diese Katalogdateien sind vom Programm unabhängig. Möchte man das Programm
in einer weiteren Sprache betreiben, so ist lediglich eine neue Katalogdatei
zu erzeugen, das eigentliche Programm muß nicht geändert werden.

Auf den Programmierer kommen dadurch aber zusätzliche Aufgaben hinzu: Es
müssen die Kataloge erzeugt werden, die Strings nach wie vor eingegeben
werden und es muß zusätzlicher Code erzeugt werden, der die Behandlung der
Kataloge übernimmt. Dies soll durch FlexCat so weit wie möglich vereinfacht
und automatisiert werden, ohne dabei auf Flexibilität (vor allem in Bezug
auf den erzeugten Quelltext) zu verzichten. Betrachten wir als Beispiel
ein Programm @file{HelloLocalWorld.c}. Das Programm wird letzten Endes so
aussehen:
@example
    #include <stdio.h>
    #include <stdlib.h>
    #include <HelloLocalWorld_Cat.h>  /* @strong{Muß} eingebunden werden! */

    void main(int argc, char *argv[])
    @{
      printf("%s\n", msgHello);
    @}
@end example
@noindent
Beachten Sie, daß dies dem originalen @file{HelloWorld.c} fast völlig
entspricht, abgesehen davon, daß der String "Hello, world!" durch eine
Konstante msgHello ersetzt wird.

Man beginnt stets damit, diese Konstanten und die zugeordneten Strings
in einer sogenannten @code{Katalogbeschreibung} abzulegen. @xref{Catalog
description}. Unsere Katalogbeschreibung würde
in einer Datei @file{HelloLocalWorld.cd} stehen und so aussehen:
@example
    ;   Kommentare sind natürlich erlaubt! Jede mit einem Semikolon
    ;   beginnende Zeile ist eine Kommentarzeile.
    ;
    ;   Die Sprache der eingebauten Strings:
    #language english
    ;
    ;   Die für den Aufruf von Locale/OpenCatalog() verwendete
    ;   Versionsnummer. Dies ist anders als bei Exec/OpenLibrary():
    ;   0 bedeutet beliebige Version, andere Nummern müssen exakt
    ;   stimmen!
    #version 0
    ;
    ;   Dies definiert einen String und die ID unter der er verwendet
    ;   wird. Die Zahl 4 gibt an, daß der String wenigstens 4 Zeichen
    ;   enthalten sollte.
    msgHello (/4/)
    Hello, world!
@end example

Mit FlexCat erzeugt man aus der Katalogbeschreibung zwei andere Dateien:
Das Includefile @file{HelloLocalWorld_Cat.h} definiert die Konstanten,
die Datei @file{HelloLocalWorld_Cat.c} enthält ein Array mit den Strings
sowie versteckte Initialisierungsroutinen. Wie diese genau aussehen, ist
unerheblich, insbesondere benötigt man keinerlei Kenntnisse der
@code{locale.library}!

Allerdings könnten Sie neugierig sein, wie diese Dateien aussehen oder
sogar ein anderes Aussehen wünschen. Hier liegt der Unterschied zwischen
FlexCat und anderen Kataloggeneratoren: Bei FlexCat ist kein bestimmtes
Format vorgeschrieben. Mit Hilfe der sogenannten Quelltextbeschreibungen
können Sie praktisch beliebige Formate vorgeben. Damit könnten z.B. auch
unter AmigaDOS 2.0 Kataloge verwendet werden. @xref{Source description}.
Solche Katalogbeschreibungen sind bei FlexCat bereits mitgeliefert
werden. Damit kann man die Quelltexte folgendermaßen erzeugen:
@example
    @samp{FlexCat HelloLocalWorld.cd HelloLocalWorld_Cat.c=C_c.sd}
    @samp{FlexCat HelloLocalWorld.cd HelloLocalWorld_Cat.h=C_h.sd}
@end example

Wenn das Programm fertig ist, dann wird FlexCat erneut verwendet, um
sogenannte @code{Katalogübersetzungen} zu erzeugen, eine für jede
weitere Sprache außer der eingebauten. @xref{Catalog translation}. Erzeugen
wir also eine deutsche Katalogübersetzung:
@example
    @samp{FlexCat HelloLocalWorld.cd NEWCTFILE Deutsch.ct}
@end example
@noindent
Die fertige Datei sieht dann so aus:
@example
    ## version
    ## language
    ## codeset 0
    ;   Kommentare sind natürlich erlaubt! Jede mit einem Semikolon
    ;   beginnende Zeile ist eine Kommentarzeile.
    ;
    ;   Die Sprache der eingebauten Strings:
    ;
    ;   Die für den Aufruf von Locale/OpenCatalog() verwendete
    ;   Versionsnummer. Dies ist anders als bei Exec/OpenLibrary():
    ;   0 bedeutet beliebige Version, andere Nummern müssen exakt
    ;   stimmen!
    ;
    ;   Dies definiert einen String und die ID unter der er verwendet
    ;   wird. Die Zahl 4 gibt an, daß der String wenigstens 4 Zeichen
    ;   enthalten sollte.
    msgHello

    ;Hello, world!
@end example
@noindent
Dies sieht der Katalogbeschreibung sehr ähnlich. FlexCat übernimmt dabei
die Kommentare, auch dort wo es nutzlos ist: Z.B. ist der Kommentar zur
Länge der Strings hier bedeutungslos, da diese bereits in der
Katalogbeschreibung angegeben werden muß. Man muß nun lediglich die
Lücken füllen, d.h. die Sprache (language, hier Deutsch), die Version
(einen typischen Versionsstring, @samp{$VER: Deutsch.catalog (11.03.94)}
wäre z.B. gut möglich) und den codeset (hier 0, siehe Locale/OpenCatalog()
für Details) sowie natürlich die übersetzten Strings selber. FlexCat
erleichtert dies, indem die originalen Strings jeweils als Kommentare
eingefügt werden.

Schließlich werden daraus die eigentlichen Kataloge erzeugt:
@example
    @samp{FlexCat HelloLocalWorld.cd Deutsch.ct CATALOG Deutsch.catalog}
@end example
@noindent
Beachten Sie, daß man dazu weder das Programm noch die Quelltexte benötigt.
Dies kann also ohne weiteres später geschehen, etwa um nachträglich weitere
Sprachen zu unterstützen. Es ist üblich und durchaus erwünscht, eine
Datei @file{NewCatalog.ct} mitzuliefern, die das Erstellen eigener Kataloge
erlaubt.

Aber was geschieht, wenn das Programm später geändert oder erweitert wird?
Dann muß nur die Katalogbeschreibung geändert werden. Mit Hilfe von
FlexCat können die Katalogübersetzungen auf den neuesten Stand gebracht
werden:
@example
    @samp{FlexCat HelloLocalWorld.cd Deutsch.ct NEWCTFILE Deutsch.ct}
@end example
@noindent
Es müssen dann lediglich noch evtl. neue Strings eingegeben werden.



@node Installation
@chapter Installation des Programms
@cindex Installation
@cindex Systemanforderungen
FlexCat sollte auf jedem Amiga mit OS 2.0 laufen.
Die erzeugten Programme sind auf @strong{jedem} Amiga lauffähig (zumindest
was die Verwendung der @code{locale.library} betrifft). Prinzipiell
sind sie sogar auf anderen Rechnern lauffähig.
Lokalisierung ist aber natürlich nur auf dem Amiga und ab der
Workbench 2.1 möglich, da erst dann die @code{locale.library}
zur Verfügung steht. @xref{Benutzung}.

Es ist aber prinzipiell durchaus möglich, auch unter einer früheren
Workbench oder gar auf anderen Rechnern Lokalisierung anzubieten: Ein
Beispiel dafür liefert die Quelltextbeschreibungsdatei @file{C_c_V20.sd},
in der die @code{locale.library} durch die
@code{iffparse.library} ersetzt wird, falls letztere vorhanden ist, erstere
dagegen nicht. Damit ist Lokalisierung schon ab der Workbench 2.0 möglich.
@xref{C}.

Zur Installation ist nichts weiter zu tun, als das eigentliche Programm
an eine sinnvolle Stelle Ihres Suchpfades zu kopieren und einen geeigneten
Platz für die Quelltextbeschreibungen auszuwählen. Möglicherweise
wollen Sie die Umgebungsvariable @var{FLEXCAT_SDDIR} setzen.
@xref{Programmstart}.

Falls Sie mit einer anderen als der englischen Sprache arbeiten wollen,
müssen Sie außerdem den entsprechenden Katalog an eine geeignete Stelle
kopieren. Im Falle der deutschen Sprache wäre dies
@file{Catalogs/Deutsch/FlexCat.catalog}. Der einfachste Platz ist das
Verzeichnis @file{Locale:Catalogs/Deutsch}, möglich ist aber auch,
einfach das ganze Verzeichnis @file{Catalogs} in das Directory des
Programms zu kopieren. @xref{Benutzung}.



@node Programmstart
@chapter Aufruf des Programms
FlexCat arbeitet nur vom CLI aus. Die Aufrufsyntax ist

@example
    FlexCat CDFILE/A,CTFILE,CATALOG/K,NEWCTFILE/K,SOURCES/M,WARNCTGAPS/S
@end example

Dies ist die Bedeutung der Argumente:
@table @strong
@item CDFILE
ist der (obligatorische) Name einer zu lesenden Katalogbeschreibung.
Aus diesem Argument wird auch der Basisname bei der Quelltextbeschreibung
gewonnen. Achten Sie deshalb auf Groß-/Kleinschreibung!
@xref{Source description}.
@item CTFILE
ist der Name einer Katalogübersetzung, die etwa für die Erzeugung eines
Katalogs zu lesen ist. Außerdem kann man eine vorhandene
Katalogübersetzung mit Hilfe des Argumentes NEWCTFILE
auf den neuesten Stand zu bringen: Wird beides angegeben, so wird zunächst
die Katalogbeschreibung und dann die -übersetzung gelesen und
anschließend eine neue Katalogübersetzung erzeugt, die dieselben
Strings wie die alte und evtl. neue Strings (als Leerzeile) enthält.
@item CATALOG
ist der Name eines zu erzeugenden Kataloges. Dieses Argument ist nur
gemeinsam mit CTFILE erlaubt.
@item NEWCTFILE
ist der Name einer neu zu erzeugenden Katalogübersetzung. Wie schon
gesagt, werden die Strings aus einer evtl. durch CTFILE angegebenen
bestehenden Datei übernommen. Fehlt das Argument CTFILE, so wird eine
Datei erzeugt, die nur Leerzeilen als Strings enthält.
@item SOURCES
sind die Namen zu erzeugender Quelltextdateien sowie der dazu zu lesenden
Quelltextbeschreibungen. Diese Argumente müssen die Form
@samp{source=template} haben, wobei @file{source} der Name der zu
erzeugenden Quelltextdatei und @file{template} der Name der
Quelltextbeschreibungsdatei ist.

Wird die angegebene Quelltextbeschreibung nicht gefunden, so sucht
FlexCat nach einer Datei gleichen Namens in @file{PROGDIR:lib}, d.h.
im Unterverzeichnis @file{lib} des Directories, in dem sich das
Programm selbst befindet. (@file{PROGDIR:lib} kann durch die
Environment-Variable @var{FLEXCAT_SDDIR} überschrieben werden.)
Beispiel: Mit
@example
    @samp{FlexCat FlexCat.cd FlexCat_Cat.c=Templates/C_c_V20.sd}
@end example
@noindent
würde zunächst nach einer Datei @file{Templates/C_c_V20.sd} im aktuellen
Directory gesucht. Würde diese nicht gefunden, und es gäbe keine
Variable @var{FLEXCAT_SDDIR}, so würde nach einer Datei
@file{lib/Templates/C_c_V20.sd} im Directory des Programms FlexCat
gesucht. Gäbe es dagegen eine Variable @var{FLEXCAT_SDDIR} und diese
hätte etwa den Wert @samp{Work:FlexCat}, so würde nach der
Datei @file{Work:FlexCat/Templates/C_c_V20.sd} gesucht.
@item WARNCTGAPS
Gewöhnlich überprüft FlexCat nicht, ob eine Quelltextübersetzung
vollständig ist, d.h. ob alle Strings aus der Quelltextbeschreibung
auch in der -übersetzung vorkommen. Diese Option erzwingt die
Überprüfung.
@end table

Für weitere Beispiele siehe @ref{Uebersicht, Übersicht, Übersicht}.



@node Catalog description
@chapter Aufbau einer Katalogbeschreibung
@cindex Katalogbeschreibung
@cindex Catalog description
@cindex .cd
Eine Katalogbeschreibungsdatei enthält vier Arten von Zeilen.

@table @strong
@item Kommentarzeilen
Jede mit einem Semikolon beginnende Zeile ist eine Kommentarzeile, wird
also von FlexCat ignoriert. (Eine Ausnahme sind die unten beschriebenen
Stringzeilen, die sehr wohl mit einem Semikolon beginnen dürfen.)

@item Kommandozeilen
Mit einem '#' beginnende Zeilen enthalten ein Kommando. Mögliche Kommandos
sind (Groß-/Kleinschreibung wird ignoriert):
@table @code
@item #language <str>
gibt die Vorgabesprache des Programms an, d.h. die Sprache der Strings in
der Katalogbeschreibungsdatei. Vorgabe ist @samp{#language english}.
@item #version <num>
gibt die Versionsnummer der zu eröffnenden Kataloge an. Im Unterschied zu
@code{Exec/OpenLibrary} muß die Nummer genau stimmen, höhere Nummern werden
nicht akzeptiert. Eine Ausnahme ist es, hier die 0 als Versionsnummer
anzugeben, durch die jeder Katalog akzeptiert wird. Vorgabe ist
@samp{#version 0}. Zu diesen Befehlen siehe auch @code{Locale/OpenCatalog}.
@item #lengthbytes <num>
Weist das Programm an, vor jeden String die angegebene Zahl von Bytes zu
schreiben, die die Länge des Strings (ohne die lengthbytes) enthalten und
ohne abschließendes NUL-Byte angeben. (Ein NUL-Byte wird in Katalogen aber
trotzdem angehängt, im erzeugten Quelltext ist dies von der
Quelltextbeschreibungsdatei abhängig.) @samp{<num>} muß zwischen 0 und
sizeof(long)=4 liegen. Vorgabe ist @samp{#lengthbytes 0}.
@item #basename <str>
Setzt den Basisnamen für die Quelltextbeschreibung. Der aus den Argumenten
beim Aufruf des Programmnamens gewonnene Basisname (@pxref{Programmstart})
wird überschrieben. @xref{Source description}.
@end table

@item Beschreibungszeilen
deklarieren einen String. Sie haben die Form @samp{IDSTR (id/minlen/maxlen)},
wobei @samp{IDSTR} ein Bezeichner ist (d.h. ein aus den Zeichen a-z,A-Z,0-9
und dem Underscore bestehender String), @samp{id} eine eindeutige Nummer
(die von jetzt an als ID bezeichnet wird) angibt, @samp{minlen} die minimale
und @samp{maxlen} die maximale Länge
des Strings. Die drei letztgenannten dürfen auch fehlen, das Programm
wählt dann selbst einen Wert für @samp{id} und erlaubt Strings beliebiger
Länge. Die auf eine Beschreibungszeile folgende ist eine

@item Stringzeile,
@cindex Steuerzeichen
@cindex Ascii-Code
d.h. sie enthält den eigentlichen String und nichts anderes. Dieser darf
eine Reihe von Steuerzeichen enthalten, die alle durch einen Backslash
eingeleitet werden:
@table @samp
@item \b
Backspace (Ascii 8)
@item \c
Control Sequence Introducer (Ascii 155)
@item \e
Escape (Ascii 27)
@item \f
Form Feed (Ascii 12)
@item \g
Display beep (Ascii 7)
@item \n
Line Feed, newline (Ascii 10)
@item \r
Carriage Return (Ascii 13)
@item \t
Tab (Ascii 9)
@item \v
Vertical tab (Ascii 11)
@item \)
Das Klammer-Zu-Zeichen. (Dies ist evtl. innerhalb einer @samp{%(..)}-Sequenz
nötig, siehe @ref{Source description}.)
@item \\
Der Backslash selbst.
@item \xHH
Das durch @samp{HH} gegebene Ascii-Zeichen, wobei @samp{HH} Hexziffern sind.
@item \OOO
Das durch @samp{OOO} gegebene Ascii-Zeichen, wobei @samp{OOO} Hexziffern sind.
@end table
@end table
Schließlich signalisiert ein einzelner Backslash am Zeilenende, daß die
Zeile (und damit der String) auf der nächsten Zeile fortgesetzt wird.
Es ist dadurch möglich, beliebig lange Strings zu definieren. (FlexCat ist
lediglich durch das verfügbare RAM eingeschränkt.)

Ein String wird also stets durch eine Beschreibungszeile und eine
unmittelbar darauffolgende Stringzeile angegeben. Ein Beispiel wäre
@example
    msgHello (/4/)
    Hello, this is english!\n
@end example
In diesem Beispiel fehlt die ID, wird also vom Programm festgesetzt. (Dies
ist sicher der einfachste und beste Weg.) Die 4 gibt hier an, daß der in
der nächsten Zeile stehende String wenigstens 4 Zeichen enthalten soll,
eine maximale Länge fehlt.

@cindex FlexCat.cd
Als ausführlicheres Beispiel zum Aufbau einer Katalogbeschreibungsdatei kann
die Datei @file{FlexCat.cd} dienen.



@node Catalog translation
@chapter Aufbau einer Katalogübersetzung
@cindex Katalogübersetzung
@cindex Catalog translation
@cindex .ct
Katalogübersetzungen entsprechen in ihrem Aufbau ganz und gar den
Katalogbeschreibungen. Nur sind auf den Kommandozeilen andere
Kommandos erlaubt und die Beschreibungszeilen enthalten keine Angaben über
ID sowie minimale oder maximale Länge, da diese aus der Katalogbeschreibung
entnommen werden. Selbstverständlich sollte jeder String aus der
Katalogbeschreibung auch in der Katalogübersetzung vorkommen und es dürfen
keine Strings (d.h. Stringbezeichner) auftauchen, die nicht auch in der
Katalogbeschreibung definiert sind. Dies zu sichern geht am einfachsten,
indem man mit FlexCat aus den evtl. geänderten Katalogbeschreibungen und den
evtl. alten Katalogübersetzungen neue erzeugt. @xref{Uebersicht,
Übersicht, Übersicht}.

Die in Katalogübersetzungsdateien erlaubten Kommandos sind:
@table @code
@item ##version <str>
Gibt die Version des Kataloges in Form eines AmigaDOS-Versionsstrings an.
Beispiel:
@example
    @samp{##version $VER: Deutsch.ct 8.1 (27.09.93)}
@end example
Die Versionsnummer dieses Kataloges ist 8. Um ihn zu eröffnen, müssten also
in der Katalogbeschreibung die Versionsnummern 0 oder 8 angegeben werden.

@item ##rcsid $Date: 2007-01-01 03:48:17 +0100 (Mo, 01. Jan 2007) $ $Revision: 73 $ $Id: FlexCat_german.texinfo 73 2007-01-01 02:48:17Z tactica $
Das Kommando @code{##version} ist etwas ungeeignet im Zusammenhang
mit rcs, dem Revision-Control-System. Aus diesem Grund kann man
statt @code{##version} auch dieses Kommando verwenden. Dabei ist
@samp{<date>} das Datum in der Form @samp{yy/mm/dd}. <time> die
Zeit (wird ignoriert), @samp{<rev>} die Versionsnummer und
@samp{<name>} der im Versionsstring zu verwendende Name.

@item ##name <name>
Dieses Kommando egibt es nur aus Kompatibilitaetsgruenden mit
@code{CatComp}. Es überschreibt den gleichnamigen Parameter
von @code{##rcsid}.

@item ##language <str>
Gibt die Sprache des Kataloges an. Natürlich sollte dies eine andere als die
Sprache der Katalogbeschreibung sein. Die Katalogsprache und die
Katalogversion @strong{müssen} angegeben werden.

@item ##codeset <num>
Ein derzeit noch unbenutztes Argument für die Eröffnung eines Kataloges.
Sollte immer 0 sein. (Dies ist auch der Vorgabewert.)

@item ##chunk <ID> <string>
Dient dazu, Kommentare in den fertigen Katalog aufzunehmen. Z.B. würde
@example
    ## chunk AUTH German catalog translation by Jochen Wiedmann
@end example
@noindent
einen Chunk namens AUTH (für Author) aufnehmen, der aus dem String
@samp{German catalog translation by Jochen Wiedmann} bestünde.
@end table

@cindex Deutsch.ct
Das obige Beispiel sieht hier so aus:
@example
    msgHello
    Hallo, dies ist deutsch!\n
@end example
@noindent
Als weiteres Beispiel einer Katalogübersetzungsdatei kann
@file{Deutsch.ct} dienen.



@node Source description
@chapter Aufbau einer Quelltextbeschreibung
@cindex Source description
@cindex Quelltextbeschreibung
@cindex .sd
Der wichtigste Teil von FlexCat ist die Quelltexterzeugung. Bis hierher
bietet FlexCat nichts, was nicht auch CatComp, KitCat und Konsorten bieten
würden. Der erzeugte Quelltext soll nun die Verwendung der erzeugten
Kataloge möglichst einfach machen. Andererseits soll dies aber unter
beliebigen Programmiersprachen und für beliebige Anforderungen gelten. Um
diese scheinbaren Widersprüche aufzulösen, kennt FlexCat die
Quelltextbeschreibungen. Das sind Dateien, die gewissermaßen die
Vorlage für den zu erzeugenden Quelltext bilden. Wie die
Katalogbeschreibungen und -übersetzungen sind sie mit einem
Editor erzeug- und bearbeitbar: Das ist es, was FlexCat so flexibel macht.

FlexCat durchsucht die Quelltextbeschreibung nach gewissen Symbolen, die
durch die in der Katalogbeschreibung gegebenen Werte ersetzt werden.
Mögliche Symbole sind zum einen die mit einem Backslash eingeleiteten
Steuerzeichen, die auch in den Strings der Katalogbeschreibung und der
Katalogübersetzung erlaubt sind, zum anderen aber Steuerzeichen, die mit
einem @key{%}-Zeichen beginnen: Für C-Programmierer ein wohlvertrautes
Konzept. Mögliche Steuerzeichen sind:

@table @samp
@item %b
ist der Basisname der Quelltextbeschreibungsdatei. (Für @file{FlexCat.cd}
als CDFILE wäre also @code{FlexCat} der Basisname. Wie schon erwähnt, kommt
es deshalb beim Argument CDFILE sehr wohl auf Groß-/Kleinschreibung an;
@pxref{Programmstart})
@item %v
ist die Versionsnummer aus der Katalogbeschreibung, nicht zu verwechseln
mit dem Versionsstring aus der Katalogübersetzung.
@item %l
ist die Sprache der Katalogbeschreibung. Bitte beachten Sie, daß hier
ein String eingesetzt wird, dessen Aussehen mit dem Kommando
@code{##stringtype} beeinflußt wird.
@item %n
ist die Anzahl der Strings in der Katalogbeschreibung.
@item %%
ist das Prozentzeichen selbst.
@end table

Das wesentlichste sind aber die folgenden Steuerzeichen. Sie repräsentieren
auf unterschiedliche Art und Weise die Strings der Katalogbeschreibung.
Zeilen die eines dieser Zeichen enthalten, werden von FlexCat für jeden
Katalogstring wiederholt, da im Normalfall kaum alle Strings in eine
Zeile passen würden.

@table @samp
@item %i
ist der Bezeichner aus der Katalogbeschreibung.
@item %nd
@itemx %nx
@itemx %nc
ist die ID des Strings im Dezimal- bzw. Hexadezimal bzw. Oktalformat.
Dabei steht @samp{n} für eine ganze Zahl, die angibt, wieviele Zeichen
die erzeugte Zahl einnehmen soll. (Es wird links mit Nullen aufgefüllt.)
Es ist möglich, die Zahl @samp{n} wegzulassen: In diesem Fall wird nichts
aufgefüllt und die erzeugte Zahl ist gerade so lang wie nötig.
@item %e
gibt an, um den wievielten String (Mit 0 beginnend) es sich handelt.
@item %s
ist der String selbst; dieser wird in einer von der Programmiersprache
abhängigen Art und Weise dargestellt. Dies kann mit den Kommandos
@code{##stringtype} und @code{##shortstrings} beeinflußt werden.
@item %(...)
gibt an, daß der zwischen den Klammern stehende Text bei allen Strings
außer dem letzten auftauchen soll. Dies ist z.B. bei Arrays nützlich,
wenn unterschiedliche Arrayeinträge durch ein Komma getrennt werden
sollen, nach dem letzten aber kein Komma mehr kommen soll: Dann würde
man nach dem Stringeintrag eben @samp{%(,)} schreiben. Beachten Sie, daß
der Text zwischen den Klammern nicht weiter auf @samp{%}-Symbole untersucht
wird. Backslash-Sequenzen sind allerdings weiter erlaubt.
@end table

Die Steuerzeichen @samp{%l} und @samp{%s} erzeugen Strings. Die Darstellung
von Strings hängt natürlich von der Programmiersprache ab, für die Quelltext
erzeugt werden soll. Deshalb können in die Quelltextbeschreibung ähnlich
wie in der Katalogübersetzung Kommandos eingebaut werden. Diese müssen am
Zeilenanfang stehen und jeweils eine eigene Zeile einnehmen. Die möglichen
Kommandos sind:
@table @code
@item ##shortstrings
gibt an, daß lange Strings über mehrere Zeilen verteilt werden dürfen.
Dies ist nicht in allen Programmiersprachen ohne weiteres möglich und
vor allem besonders stark von der verwendeten Programmiersprache abhängig.
Deshalb werden vorgabemäßig notfalls eben sehr lange Zeilen erzeugt.
@item ##stringtype <art>
gibt die Syntax der Strings an. Mögliche Arten sind:
@table @strong
@item None
Es werden keinerlei zusätzliche Zeichen erzeugt und lediglich die
Zeichen des Strings ausgegeben. Es ist keine Ausgabe von Binärzeichen (das
sind die mit dem Backslash erzeugten Zeichen) möglich.
@item C
erzeugt Strings gemäß den Regeln der Programmiersprache C, d.h. die Strings
werden links und rechts mit je einem Anführungszeichen abgegrenzt. Falls
Strings über mehrere Zeilen verteilt werden, so werden die Zeilen bis auf
die letzte mit einem Backslash beendet. (Der Backslash ist innerhalb
von Makros nötig.) Steuerzeichen werden mit @samp{\OOO} ausgegeben.
@xref{C}.
@item Oberon
wie der Stringtyp bei C, allerdings wird kein Backslash bei Zeilentrennung
erzeugt. @xref{Oberon}. Dieser Stringtyp wird auch für Modula-2
empfohlen.
@item Assembler
Strings werden mit @samp{dc.b} erzeugt und links und rechts mit einem
einfachen Anführungsstrich abgegrenzt. Binärzeichen werden mit $XX erzeugt.
@xref{Assembler}.
@item E
Strings werden mit je einem ' umgeben. Mehrzeilihe Strings werden durch
ein '+' konkateniert. Binärzeichen win in C.
@end table
@end table

Als Beispiel betrachten wir einen Auszug aus der Quelltextbeschreibungsdatei
@file{C_h.sd}, die eine Include-Datei für die Programmiersprache C
erzeugt:
@example
##stringtype C
##shortstrings

#ifndef %b_CAT_H    /*  Sicherstellen, daß Include-Datei    */
#define %b_CAT_H    /*  nur einmal verwendet wird.          */


#ifndef EXEC_TYPES_H            /*  Nötige andere Include-  */
#include <exec/types.h>         /*  Dateien einbinden.      */
#endif
#ifndef LIBRARIES_LOCALE_H
#include <libraries/locale.h>
#endif


/*  Prototypen  */
extern void Open%bCatalog(struct Locale *, STRPTR);
extern void Close%bCatalog(void);
extern STRPTR Get%bString(LONG);

/*  Definitionen der Bezeichner und ihrer ID's              */
#define %i %d   /*  Diese Zeile wird für jeden Katalog-     */
                /*  wiederholt.                             */

#endif
@end example

Zum Suchpfad von Quelltextbeschreibungen siehe auch @ref{Programmstart}.




@node Benutzung
@chapter Benutzung in eigenen Programmen
@cindex Benutzung
Wie der Quelltext benutzt wird, hängt natürlich vom erzeugten Quelltext und
damit von den jeweiligen Quelltextbeschreibungen ab.
@xref{Source description}. Es kann hier deshalb nur auf die mit FlexCat
mitgelieferten Quelltextbeschreibungsdateien eingegangen werden.

Alle diese Dateien sind so aufgebaut, daß das fertige Programm auf jeden
Fall auch ohne die @code{locale.library} arbeitet. Üblicherweise muß
die @code{locale.library} eröffnet werden, aber das machen moderne
Compiler meist automatisch, ebenso den Aufruf der Initialisierungsroutinen.
Natürlich werden ohne @code{locale.library} nur die eingebauten Strings
aus der Katalogbeschreibung verwendet. (Die C-Quelltextbeschreibung erlaubt
allerdings auch eine Lokalisierung unter Workbench 2.0: Dabei wird die
@code{iffparse.library} benutzt, um die Kataloge quasi von Hand zu lesen.
@xref{C}.) Als Programmierer
benötigen Sie keinerlie Kenntnisse dieser Libraries, außer Sie wollen
eigene Quelltextbeschreibungen erzeugen.

Es gibt lediglich 3 Funktionen, die aufzurufen recht simpel ist:
@deffn {} OpenCatalog (locale, language)
Diese Funktion versucht, einen Katalog zu eröffnen. Das Argument
@code{locale} ist ein Zeiger auf eine Locale-Struktur, @code{language} ein
Zeiger auf einen String, der den Namen der gewünschten Sprache enthält.
Beide Argumente werden an die Locale-Funktion OpenCatalog übergeben und
sollten normalerweise immer NULL (bzw. NIL) sein, da andernfalls die
Voreinstellungen des Benutzers überschrieben werden. Näheres ist in den
AutoDocs nachzulesen.

Unter nicht-objektorientierten Sprachen heißt diese Funktion
@samp{OpenXXXCatalog}, wobei @samp{XXX} der Basisname des Programms ist.

Hat der Benutzer als Vorgabesprachen etwa @samp{Deutsch} und @samp{Français}
eingestellt und der Basisname des Programms ist @samp{XXX}, so wird
nacheinander nach folgenden Dateien gesucht:
@example
    @file{PROGDIR:Catalogs/Deutsch/XXX.catalog}
    @file{LOCALE:Catalogs/Deutsch/XXX.catalog}
    @file{PROGDIR:Catalogs/Français/XXX.catalog}
    @file{LOCALE:Catalogs/Français/XXX.catalog}
@end example
Dabei ist @file{PROGDIR:} das aktuelle Directory des Programms. Die
Reihenfolge von @file{PROGDIR:} und @file{LOCALE:} kann evtl. vertauscht
werden, falls dadurch ein Requester wie @samp{Insert volume YYY} unterdrückt
werden kann.

OpenCatalog ist vom Typ void (für Modula2-Programmierer: Eine Prozedur),
liefert also kein Ergebnis.
@end deffn

@deffn {} GetString (ID)
Diese Funktion liefert einen Zeiger auf den Katalogstring mit der
angegebenen Nummer. Die ID wird in der Katalogbeschreibung definiert.
Es versteht sich von selbst, daß die Strings Eigentum der
@code{locale.library} sind und deshalb nicht verändert werden dürfen.

Ein Beispiel ist vielleicht nützlich. Im Beispiel aus der Katalogbeschreibung
wird der String @code{msgHello} definiert. Die Quelltextbeschreibungen
deklarieren nun eine Konstante @samp{msgHello}, der die ID repräsentiert.
Damit könnte der String in C so ausgegeben werden:
@example
    printf("%s\n", GetString(msgHello));
@end example
@end deffn

@deffn {} CloseCatalog (void)
Mit dieser Funktion wird der Katalog (das heißt das belegte RAM) vor dem
Programmende wieder freigegeben. Die Funktion kann gefahrlos zu jeder
Zeit aufgerufen werden, sogar wenn OpenCatalog gar nicht aufgerufen wurde.
@end deffn

@menu
* C::         FlexCat-Quelltext in C-Programmen
* C++::       FlexCat-Quelltext in C++-Programmen
* Oberon::    FlexCat-Quelltext in Oberon-Programmen
* Modula-2::  FlexCat-Quelltext in Modula-2-Programmen
* Assembler:: FlexCat-Quelltext in Assembler-Programmen
* E::         FlexCat-Quelltext in E-Programmen
@end menu



@node C
@section FlexCat-Quelltext in C-Programmen
@cindex C
@cindex C_c.sd
@cindex C_h.sd
Der C-Quelltext besteht aus zwei Teilen: Einer @file{.c}-Datei, die einfach
übersetzt und mit dem Linker eingebunden wird und nicht weiter zu
interessieren braucht und einer @file{.h}-Datei, die vom benutzenden Programm
mit @samp{#include} eingebunden wird. In ihr werden die ID's der Strings
als Makro definiert.

Die mir bekannten C-Compiler (SAS/C, Dice und gcc) erlauben das automatische
Eröffnen der Libraries und Kataloge, weshalb die Funktionen @code{OpenCatalog}
und @code{Closecatalog} hier entfallen. (Benutzer anderer Compiler müssen
diese Funktionen aber sehr wohl aufrufen.) Ferner ist die
C-Quelltextbeschreibung so angelegt, daß die @code{GetString}-Funktion bereits
für alle Strings bei der Initialisierung aufgerufen wird: Man kann deshalb
einfach @samp{msgHello} statt @samp{GetString(msgHello)} schreiben.

Definiert man beim Compilieren die Konstante @code{LOCALIZE_V20} (das heißt,
man compiliert bei gcc und Dice mit @samp{-DLOCALIZE_V20} bzw. bei SAS/C
mit @samp{DEF LOCALIZE_V20}) so wird
Quelltext erzeugt, der auch unter Workbench 2.0 Kataloge lesen kann.
Allerdings muß dann die @code{iffparse.library} eröffnet werden, ferner
ist unmittelbar nach dem Start von @code{main} aus eine Funktion
@code{InitXXXCatalog} aufzurufen, die als Argument den Namen der zu
verwendenden Sprache bekommt. (@samp{XXX} ist der Basisname des Programms.)
Diese Sprache muß dem Programm natürlich über eine Option wie
@samp{LANGUAGE Deutsch} mitgeteilt werden. Mit der @code{locale.library}
wird diese Möglichkeit natürlich ignoriert.
(Prinzipiell wäre das auch unter OS 1.3 möglich, aber ich halte eine
Unterstützung dieser veralteten Version des OS für nicht mehr nötig.)

Um diese Funktionalität zu gewähren, sind gewisse Einschränkungen nötig:
So ist es z.B. nicht möglich, eine @code{Locale}-Struktur bei der
Initialisierung anzugeben. Für 95% aller Anwendungen
dürfte dies aber völlig ausreichend sein, für andere Anwendungen muß man
eine modifizierte Quelltextbeschreibung verwenden.

Ein Beispiel eines so geschriebenen C-Programms findet man in
@ref{Uebersicht, Übersicht, Übersicht}.





@node C++
@section FlexCat-Quelltext in C++-Programmen
@cindex C++
@cindex C++_cc.sd
@cindex C++_h.sd
@cindex C++_CatalogF.cc
@cindex C++_CatalogF.h
Unter C++ ist alles dank einer geeigneten Klasse extrem einfach:
Durch Konstruktoren und Destruktoren wird das meiste automatisch
erledigt. Diese Klasse ist in den Dateien @file{C++_CatalogF.cc}
und @file{C++_CatalogF.h} implementiert, die in @file{CatalogF.cc} und
@file{CatalogF.h} umbenannt und übersetzt werden sollten. Ferner
sollten mit Hilfe der Quelltextbeschreibungen @file{C++_cc.sd} und
@file{C++_h.sd} zwei weitere Dateien erzeugt werden: Erstere enthält
die Strings, letztere wird mit @code{#include} im eigentlichen Programm
eingebunden und enthält die nötigen Deklarationen.

Abschließend ein Beispiel eines C++-Programms:
@example
    #include <iostream.h>
    extern "C"
    @{
    #include <clib/exec_protos.h>
    @}
    #include "CatalogF.h"
    #include "HelloLocalWorld_Cat.h"

    struct LocaleBase *LocaleBase = 0;

    int main()
    @{ //  Die Library muß hier eröffnet werden, auch wenn der Compiler
      //  das automatisch kann. @strong{Kein} Aussteigen, falls die
      //  Library nicht eröffnet werden kann: Dann werden einfach die
      //  eingebauten Strings verwendet.
      LocaleBase = (struct LocaleBase *) OpenLibrary("locale.library", 38);

      const CatalogF cat(0, 0, HelloLocalWorld_ARGS);

      cout >> cat.GetString(msgHelloLocalWorld);

      if (LocaleBase)
          CloseLibrary(LocaleBase);
    @}
@end example
Für den gcc ist eine Modifikation der @file{libauto.a} verfügbar, die sogar
die Eröffnung der Locale.library überflüssig macht.



@node Oberon
@section FlexCat-Quelltext in Oberon-Programmen
@cindex Oberon
@cindex Oberon_V38.sd
@cindex Oberon_V39.sd
@cindex AmigaOberon.sd
@cindex Oberon-A.sd
Es gibt unterschiedliche Quelltextbeschreibungen:
@file{AmigaOberon.sd} ist für die aktuelle Version des AmigaOberon-Compilers,
@file{Oberon_V39.sd} für ältere Versionen dieses Compilers gedacht.
@file{Oberon_V38.sd} verwendet das von @file{Locale.mod} von
Hartmut Goebel. @file{Oberon-A.sd} ist natürlich für den gleichnamigen
Compiler.

Die Prototypen der Funktionen sind:
@example
    XXX.OpenCatalog(loc: Locale.LocalePtr; language : ARRAY OF CHAR);
    XXX.GetString(num: LONGINT): Exec.StrPtr;
    XXX.CloseCatalog();
@end example
@noindent
Dabei ist @samp{XXX} jeweils der Basisname aus der Quelltextbeschreibung.
@xref{Source description}.

Zum Schluß noch ein Beispiel eines Programms, das den von FlexCat erzeugten
Quelltext verwendet:
@example
    MODULE HelloLocalWorld;

    IMPORT  x:=HelloLocalWorld_Cat; Dos;

    BEGIN
      x.OpenCatalog(NIL, "");

      Dos.PrintF("%s\n", x.GetString(x.msgHello));

      (* Katalog wird beim Programmende automatisch *)
      (* geschlossen.                               *)
    END Irgendwas;
@end example



@node Modula-2
@section Flexcat-Quelltext in Modula-2-Programmen
@cindex Modula-2
@cindex Modula2Def.sd
@cindex Modula2Mod.sd
Wie Oberon unterstützt Modula-2 ein Modulkonzept, die Funktionsnamen sind
also dieselben. Da Modula je ein Definitions- und Implementationsmodul
benötigt, müssen diese durch die Quelltextbeschreibungen
@file{Modula2Def.sd} bzw. @file{Modula2Mod.sd} erzeugt werden, die an den
M2Amiga-Compiler angepasst sind. Außerdem wird die Definitionsdatei
@file{OptLocaleL.def} benötigt, die mit dem Update auf M2Amiga v4.3
ausgeliefert wird.

Die Prototypen der Funktionen sind:
@example
    PROCEDURE OpenCatalog(loc : ld.LocalePtr;
                          language : ARRAY OF CHAR);
    PROCEDURE CloseCatalog();
    PROCEDURE GetString(num : LONGINT) : ld.StrPtr;
@end example

Zum Schlu"s noch ein Beispiel eines Programms, das den von FlexCat
erzeugten Quelltext verwendet:
@example
    MODULE HelloLocalWorld;

    IMPORT hl: HelloLocalWorldLocale,
           io: InOut;

    BEGIN
      hl.OpenCatalog(NIL, "");

      io.WriteString(hl.GetString(hl.msgHello)); io.WriteLn;

      hl.CloseCatalog;
    END HelloLocalWorld.
@end example




@node Assembler
@section FlexCat-Quelltext in Assembler-Programmen
@cindex Assembler
@cindex AztecAs_asm.sd
@cindex AztecAs_i.sd
@cindex SASasm_a.sd
@cindex SASasm_i.sd
Es gibt Quelltextbeschreibungen für die Assembler von Aztec-C bzw. SAS/C.
Beide sind im wesentlichen identisch, vor allem der SAS-Assembler dürfte
sich kaum von verbreiteten Assemblern unterscheiden. Es sollte also kein
großes Problem sein, daraus eine eigene Quelltextbeschreibung zu machen.
Der Quelltext besteht aus zwei Teilen: Einer @file{.asm}- bzw.
@file{.a}-Datei, die einfach übersetzt und mit dem Linker eingebunden
wird und nicht weiter zu interessieren braucht und einer @file{.i}-Datei,
die vom benutzenden Programm mit @samp{include} eingebunden wird. In ihr
werden die ID's der Strings definiert.

Um theoretisch auch das gleichzeitige Eröffnen mehrerer Kataloge zu
ermöglichen, tragen die FlexCat-Funktionen etwas geänderte Namen, nämlich
@samp{OpenXXXCatalog}, @samp{CloseXXXCatalog} und @samp{GetXXXString}. Dabei
ist @samp{XXX} der Basisname aus der Quelltextbeschreibung. Das Konzept ist
von der @code{GadToolsBox} übernommen und meines Erachtens bewährt.
@xref{Source description}.

Die Funktionen liefern wie üblich das Ergebnis in d0 und sichern die
Register d2-d7 und a2-a7. OpenCatalog erwartet seine Argumente in a0
(Zeiger auf Locale-Struktur) und in a1 (Zeiger auf String mit zu
verwendender Sprache). Wie schon erwähnt, sollten diese Argumente im
Normalfall immer NULL sein. GetString erwartet in a0 einen Zeiger. Auf was
er zeigt braucht ebenfalls nicht zu interessieren.

Zum Schluß noch ein Beispiel eines Programms, das FlexCat verwendet.
@example
*   HelloLocalWorld.asm

        include "HelloLocalWorld_Cat.i"
                /*  Enthält xref OpenHelloLocalWorldCatalog usw.    */

        xref    _LVOOpenLibrary
        xref    _LVOCloseLibrary
        xref    _AbsExecBase

        dseg
LocNam: dc.b    "locale.library",0
        dc.l    _LocaleBase,4       ; Dieser Name ist obligatorisch

        cseg

main:   move.l  #38,d0              ; Locale eröffnen
        lea     LocName,a1
        move.l  _AbsExecBase.a6
        jsr     _LVOOpenLibrary(a6)
*  KEIN Abbruch, falls OpenLibrary() nicht erfolgreich! (Natürlich nur,
*   wenn Locale-Funktionen nicht anderweitig benutzt werden.

        sub.l   a0,a0
        sub.l   a1,a1
        jsr     OpenHelloLocalWorldCatalog  ; Katalog eröffnen

        lea.l   msgHello,a0         ; Zeiger auf String holen
        jsr     GetHelloLocalWorldString
        jsr     PrintD0             ; und ausgeben

        jsr     CloseHelloLocalWorldCatalog ; Katalog schließen
        move.l  _LocaleBase,a1      ; Locale evtl. schließen
        move.l  a1,d0
        beq     Ende
        jsr     CloseLibrary
Ende:
        rts
        end
@end example




@node E
@section FlexCat-Quelltext in E-Programmen
@cindex E
@cindex E21b.sd
@cindex E30b.sd
Seit der Version 3.0 erlaubt E das Aufteilen von Programmen in separate
Module. Im Folgenden wird nur die Quelltextbeschreibung @file{E30b.sd}
beschrieben, die ab E3.0b funktionieren sollte. (Version 3.0a enthält
signifikante Fehler, für frühere Versionen gibt es @file{E21b.sd}, das
allerdings die Einbindung des von FlexCat erzeugten Quelltextes in den
eigentlichen Quelltext von Hand erfordert.)

@file{E30b.sd} erzeugt ein Modul @file{Locale}, das eine Variable
namens @code{cat} vom Typ @samp{catalog_XXX} bereit stellt. (Wobei
@samp{XXX} der Basisname aus der Quelltextbeschreibung ist,
@pxref{Source description}) Eine Datei @file{HelloLocalWorld.e}
könnte so aussehen:
@example
    MODULE '*Locale'
        -> Einbindung des Moduls

    DEF cat : PTR TO catalog_HelloLocalWorld
        -> Diese Variable enthält die ganzen Katalogstrings und stellt
        -> einige Methoden bereit. Sie muß in jedem Modul deklariert
        -> werden, das den Katalog verwendet, allerdings nur im
        -> Hauptmodul initialisiert werden.

    PROC main()

        localebase := OpenLibrary('locale.library', 0)
            -> Locale.library eröffnen; @strong{Kein} Abbruch, falls
            -> nicht vorhanden! (In diesem Fall werden die eingebauten
            -> Strings verwendet.

        NEW cat.create()
        cat.open()
            -> Diese Initialisierung wird (wie schon erwähnt) nur im
            -> Hauptmodul durchgeführt.

        WriteF('\s\n', cat.msg_Hello_world.getstr())
            -> cat.msg_Hello_world ist einer der in cat enthaltenen
            -> Strings. Dieser stellt eine Methode getstr() bereit,
            -> die den Katalog liest und einen Zeiger auf den zu
            -> verwendenden String liefert.

        cat.close()
        IF localebase THEN CloseLibrary(localebase)
    ENDPROC
@end example





@node Zukunft
@unnumbered Weiterentwicklung des Programms
@cindex Zukunft
@cindex Weiterentwicklung
@cindex Beiträge
Ich beabsichtige eigentlich nicht, das Programm wesentlich
weiterzuentwickeln, denke auch nicht, daß das nötig sein wird, bin aber
natürlich trotzdem für jegliche Anregung, Vorschläge oder notfalls auch
Kritik offen. Was ich auf jeden Fall gerne machen werde, sind andere
Stringtypen, falls sich diese für andere Programmiersprachen als notwendig
erweisen sollten.

Ferner wäre ich auf jeden Fall dankbar für weitere Quelltextbeschreibungen
und würde diese gerne in einer späteren Version öffnetlich zugänglich
machen - egal, welche Programmiersprache oder mit welchen Erweiterungen.
Voraussetzung ist natürlich, daß der von diesen Quelltextbeschreibungen
erzeugte Code in einem laufenden Programm erfolgreich erprobt wurde.

Ebenso dankbar wäre ich natürlich auch für neue Kataloge. Es genügt der
Eintrag der entsprechenden Strings in der Datei @file{NewCatalogs.ct}.
Wie das geht, sollte nach der Lektüre dieser Dokumentation hoffentlich klar
sein.



@node Danksagungen
@unnumbered Danksagungen
@cindex Danksagungen
Danken möchte ich:

@table @strong
@item Albert Weinert
für KitCat, den Vorgänger von FlexCat, der mir gute Dienste geleistet hat,
aber irgendwann eben nicht flexibel genug war sowie für die
Oberon-Quelltextbeschreibungen.

@item Reinhard Spisser und Sebastiano Vigna
für die Amiga-Version von texinfo, mit der diese Dokumentation geschrieben
ist.

@item Der Free Software Foundation
für die Urversion von texinfo und für viele andere hervorragende Programme.

@item Matt Dillon
für DICE und besonders für DME.

@item Alessandro Galassi
für den italienischen Katalog.

@item Lionel Vintenat
für die E-Quelltextbeschreibung und ihre Dokumentation, den französichen
Katalog und Fehlermeldungen.

@item Antonio Joaquín Gomez Gonzalez (u0868551@@oboe.etsiig.uniovi.es)
für die C++-Quelltextbeschreibung, den spanischen Katalog, die Übersetzung
der Dokumentation in Spanisch sowie für den guten Tip über die schnellere
GetString-Routine.

@item Olaf Peters (op@@hb2.maus.de)
für die Modula-2-Quelltextbeschreibung.

@item Russ Steffen (steffen@@uwstout.edu)
für die Anregung der FLEXCAT_SDDIR-Variablen.

@item Lauri Aalto (kilroy@@tolsun.oulu.fi)
für die finnischen Quelltextübersetzungen.

@item Marcin Orlowski (carlos@@felix.univ.szczecin.pl)
für die polnischen Quelltextübersetzungen

@item Udo Schuermann (walrus@@wam.umd.edu)
für die Vorschläge der WARNCTGAPS-Option und das ##chunk-Kommando.

@item Christian Hoj (cbh@@vision.auc.dk)
für die dänische Quelltextbeschreibung

@item Hartmut Goebel (hartmut@@oberon.nbg.sub.org)
für den Hinweis auf die Enforcerhits und den Vorschlag mit
##rcsid und ##name

@item Den Leuten von #AmigaGer
für die Beantwortung vieler dummer
Fragen und für viele Augenblicke erfreulich
ungezügelten Schwachsinns :-), z.B.
stefanb (Stefan Becker), PowerStat (Kai Hoffmann), \
ill (Markus Illenseer), Quarvon (Jürgen Lang), ZZA (Bernhard Möllemann),
Tron (Mathias Scheler), mungo (Ignatios Souvlatzis), \
jow (Jürgen Weinelt) und Stargazer (Petra Zeidler).

@item Commodore
für den Amiga und für die Kickstart 2.0 :-) Macht weiter mit der Kiste, dann
bin ich vielleicht auch die nächsten 8 Jahre Amiga-Benutzer!
@end table



@headings off
@node Index
@unnumbered Index
@printindex cp

@contents

@bye