Support for C#.

4 files changed, 219 insertions, 4 deletions

diff --git a/gettext-tools/doc/ChangeLog b/gettext-tools/doc/ChangeLog
index 17182b9..3f903a4 100644
--- a/gettext-tools/doc/ChangeLog
+++ b/gettext-tools/doc/ChangeLog
@@ -1,3 +1,10 @@
+2003-12-26  Bruno Haible  <bruno@clisp.org>
+
+	Support for C#.
+	* gettext.texi (C#): Add more details.
+	* msgfmt.texi: Document --csharp option and C# mode.
+	* msgunfmt.texi: Document --csharp option and C# mode.
+
 2003-12-14  Bruno Haible  <bruno@clisp.org>
 
 	* gettext.texi (PO Files): Mention csharp-format.
diff --git a/gettext-tools/doc/gettext.texi b/gettext-tools/doc/gettext.texi
index 603e845..b482636 100644
--- a/gettext-tools/doc/gettext.texi
+++ b/gettext-tools/doc/gettext.texi
@@ -2117,6 +2117,7 @@ System.out.println(
                          new Object[] @{ object1, object2 @}));
 @end example
 
+@noindent
 Similarly, in C#, you would change
 
 @example
@@ -8340,7 +8341,7 @@ directory: @code{hello-java}, @code{hello-java-awt}, @code{hello-java-swing}.
 
 @table @asis
 @item RPMs
-pnet, pnetlib
+pnet, pnetlib 0.6.2 or newer, or mono 0.29 or newer
 
 @item File extension
 @code{cs}
@@ -8352,13 +8353,15 @@ pnet, pnetlib
 _("abc")
 
 @item gettext/ngettext functions
----
+@code{GettextResourceManager.GetString},
+@code{GettextResourceManager.GetPluralString}
 
 @item textdomain
----, use @code{ResourceManager} instead
+@code{new GettextResourceManager(domain)}
 
 @item bindtextdomain
----
+---, compiled message catalogs are located in subdirectories of the directory
+containing the executable
 
 @item setlocale
 automatic
@@ -8382,6 +8385,147 @@ fully portable
 ---
 @end table
 
+Before marking strings as internationalizable, uses of the string
+concatenation operator need to be converted to @code{String.Format}
+invocations.  For example, @code{"file "+filename+" not found"} becomes
+@code{String.Format("file @{0@} not found", filename)}.
+Only after this is done, can the strings be marked and extracted.
+
+GNU gettext uses the native C#/.NET internationalization mechanism, namely
+the classes @code{ResourceManager} and @code{ResourceSet}.  Applications
+use the @code{ResourceManager} methods to retrieve the native language
+translation of strings.  An instance of @code{ResourceSet} is the in-memory
+representation of a message catalog file.  The @code{ResourceManager} loads
+and accesses @code{ResourceSet} instances as needed to look up the
+translations.
+
+There are two formats of @code{ResourceSet}s that can be directly loaded by
+the C# runtime: @code{.resources} files and @code{.dll} files.
+
+@itemize @bullet
+@item
+The @code{.resources} format is a binary file usually generated through the
+@code{resgen} or @code{monoresgen} utility, but which doesn't support plural
+forms.  @code{.resources} files can also be embedded in .NET @code{.exe} files.
+This only affects whether a file system access is performed to load the message
+catalog; it doesn't affect the contents of the message catalog.
+
+@item
+On the other hand, the @code{.dll} format is a binary file that is compiled
+from @code{.cs} source code and can support plural forms (provided it is
+accessed through the GNU gettext API, see below).
+@end itemize
+
+Note that these .NET @code{.dll} and @code{.exe} files are not tied to a
+particular platform; their file format and GNU gettext for C# can be used
+on any platform.
+
+To convert a PO file to a @code{.resources} file, the @code{resgen}
+program (from the @code{pnet} package) or the @code{monoresgen} program
+(from the @code{mono}/@code{mcs} package) can be used.  These programs
+can also convert a @code{.resources} file back to a PO file.  But beware:
+as of this writing (January 2004), the @code{monoresgen} converter is quite
+buggy and the @code{resgen} converter ignores the encoding of the PO files.
+
+To convert a PO file to a @code{.dll} file, the @code{msgfmt} program can be
+used with the option @code{--csharp}.  The result will be a @code{.dll} file
+containing a subclass of @code{GettextResourceSet}, which itself is a subclass
+of @code{ResourceSet}.  To convert a @code{.dll} file containing a
+@code{GettextResourceSet} subclass back to a PO file, the @code{msgunfmt}
+program can be used with the option @code{--csharp}.
+
+The advantages of the @code{.dll} format over the @code{.resources} format
+are:
+
+@enumerate
+@item
+Freedom to localize: Users can add their own translations to an application
+after it has been built and distributed.  Whereas when the programmer uses
+a @code{ResourceManager} constructor provided by the system, the set of
+@code{.resources} files for an application must be specified when the
+application is built and cannot be extended afterwards.
+@c If this were the only issue with the @code{.resources} format, one could
+@c use the @code{ResourceManager.CreateFileBasedResourceManager} function.
+
+@item
+Plural handling: A message catalog in @code{.dll} format supports the plural
+handling function @code{GetPluralString}.  Whereas @code{.resources} files can
+only contain data and only support lookups that depend on a single string.
+
+@item
+The @code{GettextResourceManager} that loads the message catalogs in
+@code{.dll} format also provides for inheritance on a per-message basis.
+For example, in Austrian (@code{de_AT}) locale, translations from the German
+(@code{de}) message catalog will be used for messages not found in the
+Austrian message catalog.  This has the consequence that the Austrian
+translators need only translate those few messages for which the translation
+into Austrian differs from the German one.  Whereas when working with
+@code{.resources} files, each message catalog must provide the translations
+of all messages by itself.
+
+@item
+The @code{GettextResourceManager} that loads the message catalogs in
+@code{.dll} format also provides for a fallback: The English @var{msgid} is
+returned when no translation can be found.  Whereas when working with
+@code{.resources} files, a language-neutral @code{.resources} file must
+explicitly be provided as a fallback.
+@end enumerate
+
+On the side of the programmatic APIs, the programmer can use either the
+standard @code{ResourceManager} API and the GNU @code{GettextResourceManager}
+API.  The latter is an extension of the former, because
+@code{GettextResourceManager} is a subclass of @code{ResourceManager}.
+
+@enumerate
+@item
+The @code{System.Resources.ResourceManager} API.
+
+This API works with resources in @code{.resources} format.
+
+The creation of the @code{ResourceManager} is done through
+@smallexample
+  new ResourceManager(domainname, Assembly.GetExecutingAssembly())
+@end smallexample
+@noindent
+
+The @code{GetString} function returns a string's translation.  Note that this
+function returns null when a translation is missing (i.e. not even found in
+the fallback resource file).
+
+@item
+The @code{GNU.Gettext.GettextResourceManager} API.
+
+This API works with resources in @code{.dll} format.
+
+Reference documentation is in the
+@uref{csharpdoc/index.html,csharpdoc directory}.
+
+The creation of the @code{ResourceManager} is done through
+@smallexample
+  new GettextResourceManager(domainname)
+@end smallexample
+
+The @code{GetString} function returns a string's translation.  Note that when
+a translation is missing, the @var{msgid} argument is returned unchanged.
+
+The @code{GetPluralString} function returns a string translation with plural
+handling, like the @code{ngettext} function in C.
+
+@cindex @code{libintl} for C#
+To use this API, one needs the @code{GNU.Gettext.dll} file which is part of
+the GNU gettext package and distributed under the LGPL.
+@end enumerate
+
+You can also mix both approaches: use the
+@code{GNU.Gettext.GettextResourceManager} constructor, but otherwise use
+only the @code{ResourceManager} type and only the @code{GetString} method.
+This is appropriate when you want to profit from the tools for PO files,
+but don't want to change an existing source code that uses
+@code{ResourceManager} and don't (yet) need the @code{GetPluralString} method.
+
+Two examples, using the second API, are available in the @file{examples}
+directory: @code{hello-csharp}, @code{hello-csharp-forms}.
+
 @node gawk, Pascal, C#, List of Programming Languages
 @subsection GNU awk
 @cindex awk
diff --git a/gettext-tools/doc/msgfmt.texi b/gettext-tools/doc/msgfmt.texi
index b072443..19d256a 100644
--- a/gettext-tools/doc/msgfmt.texi
+++ b/gettext-tools/doc/msgfmt.texi
@@ -39,6 +39,12 @@ Java mode: generate a Java @code{ResourceBundle} class.
 @opindex --java2@r{, @code{msgfmt} option}
 Like --java, and assume Java2 (JDK 1.2 or higher).
 
+@item --csharp
+@opindex --csharp@r{, @code{msgfmt} option}
+@cindex C# mode, and @code{msgfmt} program
+C# mode: generate a .NET .dll file containing a subclass of
+@code{GettextResourceSet}.
+
 @item --tcl
 @opindex --tcl@r{, @code{msgfmt} option}
 @cindex Tcl mode, and @code{msgfmt} program
@@ -102,6 +108,32 @@ The class name is determined by appending the locale name to the resource name,
 separated with an underscore.  The @samp{-d} option is mandatory.  The class
 is written under the specified directory.
 
+@subsection Output file location in C# mode
+
+@table @samp
+@item -r @var{resource}
+@itemx --resource=@var{resource}
+@opindex -r@r{, @code{msgfmt} option}
+@opindex --resource@r{, @code{msgfmt} option}
+Specify the resource name.
+
+@item -l @var{locale}
+@itemx --locale=@var{locale}
+@opindex -l@r{, @code{msgfmt} option}
+@opindex --locale@r{, @code{msgfmt} option}
+Specify the locale name, either a language specification of the form @var{ll}
+or a combined language and country specification of the form @var{ll_CC}.
+
+@item -d @var{directory}
+@opindex -d@r{, @code{msgfmt} option}
+Specify the base directory for locale dependent @file{.dll} files.
+
+@end table
+
+The @samp{-l} and @samp{-d} options are mandatory.  The @file{.dll} file is
+written in a subdirectory of the specified directory whose name depends on the
+locale.
+
 @subsection Output file location in Tcl mode
 
 @table @samp
diff --git a/gettext-tools/doc/msgunfmt.texi b/gettext-tools/doc/msgunfmt.texi
index 150bcd9..a760b50 100644
--- a/gettext-tools/doc/msgunfmt.texi
+++ b/gettext-tools/doc/msgunfmt.texi
@@ -18,6 +18,12 @@ Uniforum style .po file.
 @cindex Java mode, and @code{msgunfmt} program
 Java mode: input is a Java @code{ResourceBundle} class.
 
+@item --csharp
+@opindex --csharp@r{, @code{msgunfmt} option}
+@cindex C# mode, and @code{msgunfmt} program
+C# mode: input is a .NET .dll file containing a subclass of
+@code{GettextResourceSet}.
+
 @item --tcl
 @opindex --tcl@r{, @code{msgunfmt} option}
 @cindex Tcl mode, and @code{msgunfmt} program
@@ -56,6 +62,32 @@ or a combined language and country specification of the form @var{ll_CC}.
 The class name is determined by appending the locale name to the resource name,
 separated with an underscore.  The class is located using the @code{CLASSPATH}.
 
+@subsection Input file location in C# mode
+
+@table @samp
+@item -r @var{resource}
+@itemx --resource=@var{resource}
+@opindex -r@r{, @code{msgunfmt} option}
+@opindex --resource@r{, @code{msgunfmt} option}
+Specify the resource name.
+
+@item -l @var{locale}
+@itemx --locale=@var{locale}
+@opindex -l@r{, @code{msgunfmt} option}
+@opindex --locale@r{, @code{msgunfmt} option}
+Specify the locale name, either a language specification of the form @var{ll}
+or a combined language and country specification of the form @var{ll_CC}.
+
+@item -d @var{directory}
+@opindex -d@r{, @code{msgunfmt} option}
+Specify the base directory for locale dependent @file{.dll} files.
+
+@end table
+
+The @samp{-l} and @samp{-d} options are mandatory.  The @file{.msg} file is
+located in a subdirectory of the specified directory whose name depends on the
+locale.
+
 @subsection Input file location in Tcl mode
 
 @table @samp