--- a
+++ b/README
@@ -0,0 +1,253 @@
+MinGW catgets README
+$Id$
+
+Copyright (C) 2007, Keith Marshall
+
+Written by Keith Marshall  <keithmarshall@users.sourceforge.net>
+Last modification: 20-Dec-2007
+
+This package provides a native Win32 implementation of the POSIX National
+Language Support API, conforming generally to IEEE standard 1003.1-2001,
+and SUSv3, for adding national language message catalogue support to user
+applications.  It comprises a development library, designated libcatgets.a
+for static linking, or catgets-<n>.dll with accompanying libcatgets.dll.a
+import library for dynamic linking, with supporting nl_types.h header file,
+delivering Win32 implementations of the catopen(), catgets() and catclose()
+functions, as required by the POSIX National Language Support API; this is
+accompanied by a suitable, standards conformant `gencat' utility program,
+which is used to generate the message catalogue files, which are bound to
+user applications making use of these library functions.
+
+The MinGW catgets package is free software  It is provided AS IS, in the
+hope that it may be useful, but WITHOUT WARRANTY OF ANY KIND, not even an
+IMPLIED WARRANTY of MERCHANTABILITY, nor of FITNESS FOR ANY PARTICULAR
+PURPOSE.
+
+Permission is granted to redistribute this software, either "as is" or
+in modified form, under the terms of the GNU General Public License, as
+published by the Free Software Foundation; either version 2, or (at your
+option) any later version; see the file COPYING, for further details.
+
+
+Packaging Options
+-----------------
+
+MinGW catgets is available for download in three package formats; (the
+full text of this README file is included with each):--
+
+1) mingw-catgets-<version>-bin.tar.gz
+
+   Provides only the pre-built dynamic link library, for use by client
+   applications which are delivered in binary format.  The DLL is placed
+   in the `bin' subdirectory of the directory in which the package is
+   untarred; typically this should be the root of either the MinGW
+   tree, or the MSYS tree.
+
+2) mingw-catgets-<version>-dev.tar.gz
+
+   Provides the header files and precompiled libraries, which are needed
+   to develop `catgets' client applications, together with the associated
+   `manpage' documentation, and the `gencat' tool which must be used to
+   compile compatible message catalogues.  It should be untarred in the
+   root of the MinGW tree, and client applications should be linked with
+   the `-lcatgets' option, specified *after* the dependent object modules,
+   on the linking command line.
+
+3) mingw-catgets-<version>-src.tar.gz
+
+   Provides the full source code from which the above two packages have
+   been built; it supports building for native deployment, as the above,
+   or for deployment as components of a cross-compiler tool chain.
+
+
+Prerequisites for Building from Source
+--------------------------------------
+
+To build and install the catgets development libraries and tools, you
+require a C compiler, and tool chain, such as that provided by MinGW, and
+a build environment capable of running Bourne shell scripts, and the GNU
+`make' utility, such as that provided by MSYS.
+
+Before attempting to build MinGW catgets from source, you must ensure that
+a suitable `iconv' implementation is installed.  This is not normally the
+case, with a standard MinGW/MSYS installation, but the requirement may be
+satisfied by installing GNU libiconv; this *must* be libiconv-1.11 or later,
+and it *must* incorporate the 2007-04-23 patch, correcting a Win32 specific
+wchar_t conversion bug; you may ensure that this prerequisite is adequately
+satisfied, by installing libiconv-1.11 using the mingwPORT script from
+
+http://downloads.sourceforge.net/mingw/libiconv-1.11-mingwPORT-20070423-1.tar.bz2
+
+
+Building from Source, for use "In Place" on Win32
+-------------------------------------------------
+
+The build procedure, using MinGW and MSYS, is as follows:--
+
+1) Choose a suitable directory, where you will build the package; (it
+   must be a directory in which you have write permission).  A typical
+   example might be `~/src'; create it if necessary...
+
+       mkdir -p ~/src
+       cd ~/src
+
+2) Extract the source distribution tarball...
+
+       tar xzf [[/]path/to/]mingw-catgets-<version>.tar.gz
+
+3) Create a build directory, and make it your working directory...
+
+       mkdir mingw-catgets-<version>/build
+       cd mingw-catgets-<version>/build
+
+4) Configure the build...
+
+       ../configure [options ...]
+
+   For a typical MinGW installation, you will probably want to set, at
+   least, the `--prefix=/mingw' option; if you don't, this setting will
+   default to `--prefix=/usr/local', which is not what you want if you
+   have installed MinGW and MSYS with their standard configurations.
+
+   To see other available options, try...
+
+       ../configure --help
+
+   (You may wish to consider adjusting the `CFLAGS', or the `--mandir'
+    settings).
+
+5) Build the installable components...
+
+       make
+
+6) Install the basic development library components...
+
+       make install
+
+7) Install documentation...
+
+   This step is optional, but recommended; if you have installed, or if
+   you plan to install, the `man' package then...
+
+       make install-man
+
+   will allow you to access the manpages for gencat(1), catopen(3),
+   catgets(3) and catclose(3) from any working directory.
+
+
+Building for Cross-Hosted Use
+-----------------------------
+
+MinGW catgets may be built as a component of a cross-hosted compiler tool
+chain; this is supported directly by the build system, when a `--target'
+option differing from `--host' is specified at `configure' time.
+
+To build as a cross tool, the cross-compiler suite must already have been
+installed, and the `--target' option must be specified to match the prefix
+used to identify, and invoke the cross-compiler itself.  For example, this
+is how I build it, for use with my GNU/Linux hosted i586-mingw32-gcc tool
+chain, (which is identified by the prefix `i586-mingw32'):--
+
+1) You may, if you wish, install GNU libiconv.  However, your host may
+   already have a suitable iconv implementation, such as that provided by
+   glibc on GNU/Linux systems; if this is the case, it should suffice.
+
+2) Create the working directory to host the source tree, as described in
+   steps (1) and (2) of the standard Win32 "In Place" build procedure.
+
+3) Create a build directory, in which to progress the first stage of the
+   build, and make it your working directory...
+
+       mkdir mingw-catgets-<version>/build
+       cd mingw-catgets-<version>/build
+
+4) Configure the build...
+
+       ../configure [options ...] --prefix=<prefix> --target=i586-mingw32
+
+   As before, you may wish to review to options listed by...
+
+       ../configure --help
+
+   and adjust any you consider to be appropriate; it is important that you
+   specify a <prefix> which matches the installation path of your cross
+   compiler tool chain, and that you set the --target to match the name of
+   your cross tools -- in my case, the cross compiler is i586-mingw32-gcc,
+   and the entire tool chain shares the i586-mingw32 target prefix.
+
+5) Build and install the cross tool components...
+
+       make
+       make install
+
+   This results in building of the natively hosted tools, directly within
+   the build directory, together with the subset of the library components
+   which are needed to build these tools, and which are also compiled to
+   native object code.  Additionally, in the cross-build subdirectory, the
+   appropriate target specific cross-compiler is invoked, to build the full
+   set of libraries, as they will be required when subsequently deploying
+   the cross-tools to create applications for the target platform.
+
+   On successful completion of this cross-tools build, the cross-tools and
+   the supporting cross-compiled libraries are installed into the prefix,
+   directory, as specified in the configure command; at installation time,
+   the names of the executable cross-tool programs are qualified by the
+   addition of a program name prefix, to match the specified target.
+
+6) Install documentation...
+
+   As in the case of the natively built tool chain, step (5) does not
+   install the man pages which accompany the package.  These may be
+   separately installed by issuing the command...
+
+       make install-man
+
+   In this case, the installed man pages retain the same basic names as
+   used in the natively compiled case.  If preferred, the man pages may
+   be installed into an existing MANPATH directory, and distinguished
+   their similarly named native counterparts, by in the first instance
+   configuring with an explicit `--mandir=...' option, and then adding
+   a target specific man page name prefix, such as...
+
+       make man_prefix=i586-mingw32- install-man
+
+7) Note that step (5) builds only the cross-compiled library components,
+   which are the minimum required to support deployment of the cross-tools
+   into an existing cross-compiler tool chain; in particular, it does not
+   create a tool chain for eventual deployment on the target platform.  If
+   this is required, it may be prepared and packaged, without separate
+   configuration, by completing the partial build which has already
+   been initiated in the cross-build subdirectory...
+
+       cd cross-build
+       make
+       make bindist
+
+
+Linking MinGW Applications to use Message Catalogues
+----------------------------------------------------
+
+This package provides POSIX conformant national language support for
+MinGW applications.  Such support is added through calls to the POSIX
+standard `catopen', `catgets' and `catclose' functions, as described
+in the accompanying `man' pages.  References to these functions are
+resolved by addition of the `-lcatgets' option to the command line,
+when linking the application; both static and dynamically linked
+variants of the associated library are provided.
+
+
+Preparing the Message Catalogues
+--------------------------------
+
+Message catalogues, for use with the MinGW `catgets' implementation,
+are compiled using a POSIX conforming `gencat' tool; (when deployed as
+a component of a cross-hosted tool chain, this tool is named so as to
+maintain consistency with the cross-compiler naming convention; thus
+when the cross-compiler is built for, say, an i586-mingw32 target,
+invoked as i586-mingw32-gcc for example, then gencat would be
+consistently invoked as i586-mingw32-gencat.
+
+The command syntax, and the syntax for its message definition source
+files, is described in the accompanying `gencat' man page.
+
+$RCSfile$: end of file