source: trunk/third/gettext/djgpp/README.in @ 18200

This is a port of GNU Gettext @VER@ to MSDOS/DJGPP.


        TO USE THE GNU GETTEXT LIBRARY YOU **MUST** MODIFY YOUR C-LIBRARY.
        PLEASE, READ SECTION #2 (Installing the binary package) CAREFULLY
        TO LEARN HOW TO INSTALL THE GNU GETTEXT LIBRARY AND HOW TO CHANGE
        YOUR C-LIBRARY AND SYSTEM HEADER FILE.
        TO USE THE GNU GETTEXT LIBRARY YOU **MUST** DOWNLOAD AND INSTALL
        LICV17B.ZIP TOO. THIS IS **NOT** OPTIONAL.
        IT IS NOT RECOMMED TO DOWNLOAD THE GNU DISTRIBUTION OF GETTEXT
        BECAUSE ONLY THE DJGPP PORT WILL CONTAIN THE REQUIRED HEADER AND
        OBJECT FILE TO PATCH THE C LIBRARY.


1.:     DJGPP specific changes.
        =======================

        The DJGPP specific changes are the followings:
     1) The conflict existing between the BORLAND-compatibility gettext function
        from DJGPP's libc.a defined in conio.h and the GNU gettext function from
        libintl.a defined in libintl.h has been removed. But this conflict can not
        be removed **WITHOUT** changing a system header file and libc.a.
     1.1)  libc.a and system header changes.
        In conio.c, the BORLAND-compatibility gettext function has been renamed
        into _conio_gettext. In conio.h some code has been added to check if
        libintl.h is included or not by the same source file. If libintl.h is NOT
        included, the BORLAND-compatibility gettext function will be available as
        gettext. If libintl.h has been included then the BORLAND-compatibility
        gettext function will **ONLY** be available as _conio_gettext.
        The BORLAND-compatibility gettext function is now available as gettext
        and _conio_gettext.
     1.2)  GNU gettext library changes.
        If both headers, libintl.h and conio.h, are included in the same source
        file the gettext keyword makes **ALWAYS** reference to the GNU gettext
        function and **NEVER** to the BORLAND-compatibility gettext function.

     2) The binary package gtxt@packageversion@b.zip contains all needed files to get NLS
        support for the following DJGPP ports:
          bison-1.32 (bsn132s.zip)
          enscript-1.6.2 (ens162s.zip)
          fileutils-4.0 (fil40s.zip)
          grep-2.4 (grep24s.zip)
          id-utils-3.2 (idu32s.zip)
          make-3.79.1 (mak3791s.zip)
          recode-3.6 (rcode36s.zip)
          sed-3.02.80 (sed3028s.zip)
          sharutils-4.2c (shar42cs.zip)
          sh-utils-2.0j (shl20js.zip)
          tar-1.12a (tar112as.zip)
          texinfo-4.0 (txi40s.zip)
          textutils-2.0 (txt20s.zip)

        See section #4 for further information about this issue.
        To implement NLS support for one of those packages you will also need
        to download the following packages:
          gtxt@packageversion@b.zip (binaries of GNU Gettext @VER@)
          licv17b.zip (binaries of GNU libiconv 1.7)
          fil40b.zip  (binaries of GNU Fileutils 4.0)
          shl20jb.zip (binaries of GNU Sh-utils 2.0j)


2.:     Installing the binary package.
        ==============================

2.1.:   To use this binary package you **MUST** install licv17b.zip or later
        first. licv17b.zip provides the required functionality to recode the
        .mo files at run time from the unix charsets used to create them to the
        dos codepages used to display them. Copy the binary distribution into
        the top DJGPP installation directory. If you are installing Gettext on
        a dual DOS/WINDOWS 9X systems, you *MUST* first turn off the generation
        of numeric tails for 8.3 aliases Windows creats for long file names.
        For information about how to do this, please read the DJGPP FAQ List
        V 2.30, chapter 22.19: "How to Set Up a Dual DOS/Windows Installation".
        It should be noticed that neither the libintl.a library nor the
        binaries (xgettext.exe, gettext.exe, etc.) contain any code to handle
        nuneric tails of short file names. This implies that if you install
        the binary packages in a DOS box of Win9X (LFN) **WITHOUT** turning
        off the numeric tail generation you will **NOT** be able to use NLS
        on plain DOS. Once again: if you want NLS support on both Win9X **AND**
        on plain DOS you **MUST** turn off the numeric tail generation **BEFORE**
        installing the binary package. After having installed the package
        you can turn on numerical tail generation again if you wish.
        All this also applies to any other package that has been compiled with
        NLS support. You **MUST** turn off numeric tail generation every time
        you install a package that has been compiled with NLS or the binaries
        will **NOT** be able to find their .mo files (translations) when you
        switch to plain DOS.

2.2.:   Copy the binary distribution into the top DJGPP installation directory,
        just unzip it preserving the directory structure running *ONE* of the
        following commands:
          unzip32 gtxt@packageversion@b.zip      or
          djtarx gtxt@packageversion@b.zip       or
          pkunzip -d gtxt@packageversion@b.zip

2.3.:   Changing libc.a and conio.h.
        Apart from the ussual directories, the binary package will create the
        following directory:
          %DJDIR%/gnu/gtxt-@treeversion@/djgpp/djdev-2.03
        where %DJDIR% stands for the root of your DJGPP installation tree.
        Cd into the djdev-2.03 directory. You will find the following files:
          conio.diffs
          conio.h
          conio.o
        conio.diffs is a patch file that documents the changes I have done against
        the files of the original djdev203.zip and djlsr203.zip distributions.
        This file is not needed by the average user. conio.h is the modified header
        and conio.o is the recompiled new conio.c file that will replace the old
        conio.o contained in libc.a.

        For all commands that will follow now I will assume that you have
        cd'ed into the %DJDIR%/gnu/gtxt-@treeversion@/djgpp/djdev-2.03 directory,
        where %DJDIR% represents the path to your DJGPP installation. First,
        you should backup your old header and library. For this task, run the
        following command sequence (cp is the copy program from fil40b.zip):
          cp /dev/env/DJDIR/include/conio.h /dev/env/DJDIR/include/conio.bak
          cp /dev/env/DJDIR/lib/libc.a /dev/env/DJDIR/lib/libc.bak

        Now you can copy the new header into your include directory
        running the command:
          cp conio.h /dev/env/DJDIR/include

        Now you can substitute the old conio.o file in libc.a with the new one.
        For this task you will need the ar program from binutils.
        Run the command:
          ar -rv /dev/env/DJDIR/lib/libc.a conio.o
        You are done.

2.3.:   The NLS controling environment variables, LANG and LANGUAGE, must be
        set to their appropiate values. The exact way how these variables
        should be set depends on your operating system:

        * For Windows 98 systems:
          - Click START;
          - Choose Programs->Accessories->System Tools->System Information;
          - Click Tools in the menu-bar, then choose "System Configuration";
          - Use the tab provided there for editing your AUTOEXEC.BAT as
            explained below.

        * For Windows NT systems:
          - Right-click "My Computer", then select "Properties";
          - Click the "Environment" tab;
          - Add a new variables LANG and LANGUAGE and set their values to the
            wanted language codes file as explained below.

        * For all other systems (DOS, Windows 3.X and Windows 95): use any
          text editor, e.g. the standard EDIT, to edit the file AUTOEXEC.BAT
          in the root directory of the boot drive (usually, C:).

        The values of the two environment variables LANG and LANGUAGE should be
        set like this:

          set LANG=xx
          set LANGUAGE=yy:zz

        xx, yy and zz are place holders for the wanted language codes. For
        posible values, please read below.
        The LANG entry is obligatory, the LANGUAGE entry may be omited. The
        LANG variable selects the locale charsets (dos codepage) to be used to
        display the program's output and the catalog (.mo file) that contains
        the translated strings to be used. The LANGUAGE variable allows you to
        select an alternate catalog than the one stipulated by LANG. Replace
        xx, yy and zz by the language code of the catalogs you want to use. It
        should be noticed that LANGUAGE has *ALWAYS* higher priority than LANG.
        The LANG variable not only selects a catalog, it also specifies the dos
        codepage that will be used as locale charset. All this means that the
        translation strings contained in the catalogs (.mo files) will be
        recoded at runtime to the dos codepage stipulated by the value of LANG.
        This runtime recoding is needed because the .mo files may have been
        written using a charset that is not compatible with the charset that
        will be used on the machine and OS where the .mo files contents will be
        displayed. The .po files of the GNU packages, from which the .mo files
        are generated, are typical examples of this. Usualy, they have been
        written using some ISO-8859-nn charset (an unix charset) and shall be
        displayed on a DOS/WIN95 machine that uses some dos codepage.

        Some examples:
        If you only want to use the catalog containing the translations for
        your mother tongue (in my case the spanish translations) the above
        lines will only use the LANG variable and will look like this:

          set LANG=es

        In this case, LANG defines the locale charset (CP850 in this case) to
        be used for the on-the-fly recoding of the catalog (.mo file) contents
        **AND AT THE SAME TIME** the translation/language (.mo file) to be used.

        If you want to use the spanish (es) and german (de) catalogs the above
        lines will look like this:

          set LANG=es
          set LANGUAGE=es:de

        In this case a DJGPP binary that has been compiled with NLS support
        will first search for the spanish translation of a string. If a
        translation for that particular string can not be found in the spanish
        .mo file then it will search for a german translation of that string in
        the german .mo file and if a german translation of that string can also
        not been found it will default to display the build-in english string.
        No mather if a spanish, a german or an english build-in string is
        selected, the string is always recoded to the dos codepage stipulated
        by LANG. In this case: CP850. In the above example, LANGUAGE defines
        the set of languages to be used and their priority (from left to right).
        At the same time, LANG defines the locale charset (dos codepage) to be
        used to recode **ALL** translated string, no matter which language
        (.mo file) is used.
        If you want to reverse this search order the above lines would look
        like this one:

          set LANG=es
          set LANGUAGE=de:es

        Now let us assume that an user wants to use the swedish catalogs on
        a machine that loads codepage CP437 when it is booted. It should be
        noticed that the locale charset for Sweden is CP850 and not CP437.
        In this case, the lines must look like this:

          set LANG=en_US
          set LANGUAGE=sv

        LANG reflects the available codepage/charset and LANGUAGE selects the
        wanted translation catalog. en_US means CP437. Now, the contents of the
        catalog are recoded to CP437 instead to CP850 because CP437 is the
        codepage used to display messages on screen. Of course, not every
        combination of catalogs and locale charset (dos codepages) makes sense.
        E.G.: selecting as locale charset chinese (LANG=zh_TW) and the french
        translations (LANGUAGE=fr) will certainly not generate an usefull
        screen output.

        The content of LANG is a language code. Examples are fr for french,
        en_US for US english, etc. This language code is an alias for the
        locale charset to be used for runtime recoding. The complete list of
        all available aliases can be found in %DJDIR%/lib/charset.alias. This
        file is a table with two entries: left entry is the alias (en_US,
        de_AT, etc.), right entry is the corresponding dos codepage that will
        be used for that language code (alias). It should be noticed that it is
        also possible to select a codepage directely. E.G.: Instead of setting:

          set LANG=en_US

        you may directely set:

          set LANG=CP437

        cp437 or 437 are also valid settings for CP437. This overwrites any
        settings in charset.alias. The settings in the environment always
        overwrite the settings in charset.alias. Please note that if you omit
        LANG, LANGUAGE will not be honored at all. Because the information
        about which locale charset shall be used for recoding is needed,
        if LANG is omitted by the user this information will not be available
        and consequently LANGUAGE will be ignored and no translation at all
        will be done.
        If for some reason you want to disable NLS, then you should comment
        out the LANG variable or remove them from your AUTOEXEC.BAT file or
        select 'C' as your catalog:

          set LANG=C

        or clear it by setting:

          set LANG=

        You can also change during a DOS session in Win9X or on plain DOS the
        values of the LANG and LANGUAGE variables by setting or clearing them
        from the DOS prompt.

2.5.:   To create an entry for the gettext info docs in your dir file
        run from the top DJGPP installation directory the command:
          install-info --info-dir=./info ./info/gettext.info

2.6.:   The binaries distributed in this package have NLS support.
        E.G. run the command:
          xgettext
        and the binary should talk to you in your mother tonge, if
        supported.
        For futher information about GNU gettext please read the info docs.


3.:     Building the binaries from sources.
        ===================================

3.1.:   To build the binaries you will need the following binary packages:
          djdev203.zip (or a later but NOT a prior version)
          bsh203b.zip  (or a later but NOT a prior version)
          gcc303b.zip, bnu2112b.zip, mak3791b.zip,
          fil40b.zip, shl20jb.zip, txt20b.zip,
          txi40b.zip, grep24b.zip, sed3028b.zip,
          licv17b.zip

        If you want to run the check you will need also:
          dif272b.zip

        If you want to recreate the html docs you will also need:
          gro116b.zip  (or a later but NOT a prior version)
          perl561b.zip (or a later but NOT a prior version)

        All this packages can be found in the v2gnu directory of any
        Simtel.NET mirror.
        You must have licv17b.zip or a later version installed before
        configuring or compiling the package or the configuration and build
        process will fail due to unresolved references to libiconv.a
        You will need bsh203b.zip or later and *NOT* a prior version or the
        build will fail. The same applies to djdev203.zip.
        This updated versions have been recompiled with djdev203.zip and know
        about the "/dev/env" functionality introduced with djdev203.zip. All the
        other packages are the ones I have used to build the binaries from this
        sources. Previuos versions of this packages may do the job as well but
        I have not tested this.

3.2.:   Create a temporary directory and copy the source package into the
        directory. If you download the source distribution from one of the
        DJGPP archives, just unzip it preserving the directory structure
        running *ONE* of the following commands:
          unzip32 gtxt@packageversion@s.zip      or
          djtarx gtxt@packageversion@s.zip       or
          pkunzip -d gtxt@packageversion@s.zip

        Source distributions downloaded from one of the GNU FTP sites need
        some more work to unpack. First, you *MUST* use the `djtar' program
        to unzip the package.  That is because some file names in the official
        distributions need to be changed to avoid problems on the various
        platforms supported by DJGPP. `djtar' can rename files on the fly given
        a file with name mappings. The distribution includes a file
        `djgpp/fnchange.lst' with the necessary mappings. So you need first
        to retrieve that file, and then invoke `djtar' to unpack the
        distribution. Here is how:

          djtar -x -p -o @V@/djgpp/fnchange.lst @V@.tar.gz > lst
          djtar -x -n lst @V@.tar.gz

        (The name of the distribution archive and the top-level directory will
        be different for versions other than @VER@.)

        It is always recommended to download the DJGPP packages from some
        Simtel.NET mirror and *NOT* the original GNU distribution because
        only the binary distribution of the DJGPP port will contain the
        files needed to patch libc.a. This are: conio.h and conio.o.

3.3.:   This package is preconfigured for NLS support and for run time recoding
        due to the functionality provided by libiconv.a from licv17b.zip.
        This implies that licv17b.zip *MUST* be installed *before* you try to
        compile the package or the build process will fail.
        It should be noticed that when you compile your own binaries with NLS
        you must also *always* link with libiconv.a
        If you compile this package with a later version of libc.a or if you
        prefer no NLS support at all you will have to reconfigure this package.
        The configuration batch file of this package, located in the djgpp
        directory, allows you to enable or disable NLS support and to compile
        from a different partition than from where the sources are located.
        config.bat always configures the package for NLS support enabled and
        for in-place compilation if no options are given.
        The available NLS options are:
          NLS
          no-NLS

        If for some reason you want no NLS support you will have to reconfigure
        the package. For this purpose cd into the top srcdir (gtxt-@treeversion@)
        and run the following commands:
          make distclean
          djgpp\config no-NLS

        This step is **NOT** optional and the "distclean" option must be used.
        If you do not use the "distclean" option the config.cache file will not
        be deleted. In this case you are **NOT** reconfiguring because the
        configuration informations are read from the cache file instead of being
        newly computed.
        You **MUST** specify "no-NLS" or config.bat will default to "NLS".
        To build the programs in a directory other than where the sources are,
        you must add a parameter that specifies the source directory,
        e.g:
          x:\src\gnu\gtxt-@treeversion@\djgpp\config x:/src/gnu/gtxt-@treeversion@ no-NLS

        Lets assume you want to build the binaries in a directory placed on a 
        different drive (z:\build in this case) from where the sources are,
        then you will run the following commands:
          z:
          cd \build
          x:\src\gnu\gtxt-@treeversion@\djgpp\config x:/src/gnu/gtxt-@treeversion@ no-NLS

        If you want NLS support you will omit "no-NLS" or replace it by
        "NLS" in the above examples.
        The order of the "NLS" option and the srcdir option does *NOT* matter.
        You *MUST* use forward slashes to specify the source directory.

        This batch file will set same environment variables, make MSDOS
        specific modifications to the Makefile.ins and supply all other
        needed options to the configure script.

3.4.:   To compile the package run from the top srcdir the command:
          make

3.5.:   Now you can run the tests if you like.
        From the top srcdir run the command:
          make check

        Non test should fail.

3.6.:   To install the binaries, header, library, catalogs, and info docs
        run the following command from the top srcdir:
          make install CATALOGS="xx.gmo yy.gmo zz.gmo"
        or
          make install CATALOGS="xx.gmo yy.gmo zz.gmo" prefix=z:/some/other/place

        This will install the products into your DJGPP installation tree given
        by the default prefix "/dev/env/DJDIR". If you prefer to install them
        into some other directory you will have to set prefix to the appropiate
        value. Replace xx, yy and zz by the language codes of the catalogs you
        want to install.

3.7.:   Now you have to set the LANG environment variable.
        Please refer to section 2.3 for further information.


4.:     NLS support for other DJGPP ports.
        ==================================

        This package contains all needed files to get NLS support for the
        following DJGPP ports:
          bison-1.32 (bsn132s.zip)
          enscript-1.6.2 (ens162s.zip)
          fileutils-4.0 (fil40s.zip)
          grep-2.4 (grep24s.zip)
          id-utils-3.2 (idu32s.zip)
          make-3.79.1 (mak3791s.zip)
          recode-3.6 (rcode36s.zip)
          sed-3.02.80 (sed3028s.zip)
          sharutils-4.2c (shar42cs.zip)
          sh-utils-2.0j (shl20js.zip)
          tar-1.12a (tar112as.zip)
          texinfo-4.0 (txi40s.zip)
          textutils-2.0 (txt20s.zip)

        The files needed are placed in the NLS_for_djgpp_packages tree located
        in djgpp directory. I will explane this using grep-2.4 as example.
        This means that file names or command names may change from port to port.
        The configuration batch files and the sed scripts of every package have
        the same name as the original ones that this ones will replace. If you
        are familiar with the original package you shall have no difficulties
        in reconfigure the package for NLS support.
        Please inspect the tree NLS_for_djgpp_packages to see what files will
        be replaced.

4.1.:   To reconfigure and recompile a source package with NLS support you
        *MUST* install the gtxt@packageversion@b.zip and licv17b.zip packages
        first. NLS support will **NOT** work with any prior version of the above
        mentioned packages. Before installing gtxt@packageversion@b.zip and licv17b.zip
        you *MUST* deinstall the old packages if you ever have installed them.
        For this purpose use the provided manifest files from the old packages.
        Old packages means previous beta releases of gtxt@packageversion@b.zip and licv17b.zip
        *AND* also previous versions of gettext like gettext 0.10.32, etc.

4.2.:   We will assume that the required sources will be unzipped into
        a directory called src.
        Copy grep24s.zip into /src and decompress them preserving the directory
        structure running the command:
          unzip32 *.zip
        This will create the directory:
          /src/gnu/grep-2.4

        The binary package gtxt@packageversion@b.zip will create the directory:
          %DJDIR%/gnu/gtxt-@treeversion@/djgpp/NLS_for_djgpp_packages/grep-2.4
        This directory contains all needed files.
        The files are:
          grep-2.4/djgpp/config.bat  (new .bat file that replaces the original one.)
          grep-2.4/djgpp/config.sed  (sed script needed to modify configure.)
          grep-2.4/djgpp/config.site (defaults for configure.)

        Now we will xcopy the needed files into the original grep-2.4 directory.
        First we will cd into the grep-2.4 directory and then we will run the
        following command:
          xcopy %DJDIR%\gnu\gtxt-@treeversion@\djgpp\NLS_for_djgpp_packages\grep-2.4 /v/s/e

4.3.:   Before the package can be reconfigured, the old configuration must be
        cleared. Run the command:
          make distclean

        This will remove all Makefiles, config.h and config.cache file with old
        configuration information. This step is *NOT* optional and it must be
        used the "distclean" target.

4.4.:   Now the package can be configured running the command:
          djgpp\config
        if you want to build the products in the /src/grep-2.4 directory, or:
          c:\src\grep-2.4\djgpp\config c:/src/grep-2.4
        if you want to build the products on a different drive or directory.
        You can still configure without NLS support if you want. In this case
        simply add the option "no-NLS" to the above commands.

4.5.:   Now the package can be compiled and checked by running the commands:
          make
          make check
        The first command will create also all the available translation
        catalogs (.gmo files). Before running the tests you should clear
        the LANGUAGE and/or LANG variable or the tests will probably fail.

4.6.:   Now the products can be installed by running the command:
          make install CATALOGS="xx.gmo yy.gmo"

        Replace xx and yy by the appropiate language codeof the catalogs you
        want to install. If you omit CATALOGS then all catalogs will be installed.
        You can install into a temp directory if you want by specifying a prefix:
          make install prefix=z:/tmp CATALOGS="xx.gmo yy.gmo zz.gmo"

4.7.:   Now you have to set the LANG and LANGUAGE environment variable.
        Please refer to 2.4.


        Send GNU gettext specific bug reports to <bug-gnu-gettext@gnu.org>.
        Send suggestions and bug reports concerning the DJGPP port to
        comp.os.msdos.djgpp or <djgpp@delorie.com>.


Enjoy.

        Guerrero, Juan Manuel <st001906@hrz1.hrz.tu-darmstadt.de>