Ŀ
 XFolder National Language Support (NLS)       
 (W) (C) 1998 Ulrich Mller                    
 Readme file for Version 0.82                  
 Nov. 19, 1998                                 


Vlkommen till kllkoden fr det svenska NLS-paketet fr XFolder!

Eftersom vi antar att ganska f r motiverade att anvnda detta,
s sker ingen versttning av Ulrichs text fr att skapa filer ur detta
paket. Landskoden fr Sverige r 046, varfr filerna innehller dessa
siffror som identifikation.

Fljande filer finns i detta paket:

HELP.046 - innehller bildfilerna och html-sidorna som den svenska  
              HLP-boken har skapats frn.
INF.046 -   innehller bildfilerna och html-sidorna som den svenska
              INF-boken har skapats frn.
ndring i html-sidorna br helst ske i en vanlig redigerare t.ex. EPM.
Vi anvnde initialt Composer i Netscape Communicator, men 
den gav enorma problem genom att ta bort och lgga till TAGs som
HTML2IPF.CMD inte frstr.

Bckerna skapas genom att frst konvertera HTML-sidorna till en
IPF-fil  med HTML2IPF.CMD. Sedan skapas boken ur IPF-filen med
IPFC.EXE som finns bl.a. i OS/2 Developers Toolkit.

xfldr046.def, xfldr046.dlg, xfldr046.mak, xfldr046.rc utgr
kllkoden fr XFLDR046.DLL. Fr att kunna skapa denna mste
du ha typ OS/2 Developers Toolkit.

xfldr046.txt - utgr kllkoden till xfldr046.msg och ocks hr
krvs t.ex. OS/2 Developers Toolkit fr att skapa denna.

vriga versatta filer finns i det krbara svenska NLS-paketet
fr XFolder:

xflder046.sgs, inst046.msg, crobj046.cmd, instl046.cmd, sound046.cmd samt
xfcls046.txt. De kan ndras med en vanlig redigerare t.ex EPM.

Om du hittar fel i versttningen kontakta versttarna.

Simon Grnlund (simgron@ibm.net)
Roger Lindmark (roger-li@algonet.se)


Welcome to the XFolder NLS Toolkit!

Please read through this entire file in order to avoid anything
undesireable. If you have any questions which you think
are not covered here, feel free to contact me at
    ulrich.moeller@rz.hu-berlin.de

I know this is a LOT to read, and I'm sorry for this, but NLS
is a slightly tricky thing, and many different formats are
used.

IMPORTANT NOTE: You must unzip this package on a HPFS drive
because many files in this package contain long file names.


Changes:
========

Changes made since the initial source code release (which was for V0.80)
are logged in changelog.txt. I hope this is fairly complete.

NOTE:
If you have already started translating XFolder, please do read that
file. There are important changes, or XFolder 0.81 will not run with
your NLS files properly.


Legalese:
=========

Starting with V0.80, XFolder is placed under the GPL:

    Copyright (C) 1997-98 Ulrich Mller

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, in version 2 as it comes in the COPYING
    file of the XFolder main distribution.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

I explicitly retain my copyright to the documentation.


Quick overview:
===============

NLS packages identify themselves to the XFolder core via country
codes, as described on the "COUNTRY" page in the OS/2 Command
Reference (CMDREF.INF).
This package is prepared for creating the English NLS package, as
it comes with the default XFolder package. The language code
for English is "001".
So the first step you'll have to take is finding out your country
code. For example, Italian would be 039.

XFolder's National Language Support (NLS) is spread across several
files. These are:

 -  The NLS DLL to be put into the XFolder BIN subdirectory. This
    file contains the language-dependent parts of XFolder itself,
    notably dialogs, menus and miscellaneous strings.
    This file is called "XFLDxxx.DLL", with "xxx" being your three-
    digit language code.
    The files neccessary to translate this DLL are in the "001"
    directory.

 -  The XFolder message file introduced with V1.0 residing in the
    HELP subdirectory. This file holds all kinds of messages which
    are mostly displayed in XFolder's message boxes.
    This file is called "XFLDxxx.MSG", with "xxx" being your three-
    digit language code.
    To build this file, you'll have to translate XFLDRxxx.TXT in
    the "001" directory also.

 -  The WPS class descriptions which are displayed on the "WPS Classes"
    settings page in the "Workplace Shell" object. This was introduced
    with XFolder 1.0 also.
    This file is called "XFCLSxxx.TXT", with "xxx" being your three-
    digit language code. It also resides in the "001" directory.

 -  The XFolder help file in the HELP subdirectory. This file holds
    all the help panels that are displayed when you press F1.
    This file is called "XFLDxxx.HLP", with "xxx" being your three-
    digit language code.
    The files neccessary to translate this file are in the "HELP"
    subdirectory.

 -  The XFolder Online Reference in the XFolder main directory.
    This file is called "XFLDxxx.INF", with "xxx" being your three-
    digit language code.
    The files neccessary to translate this file are in the "INF"
    subdirectory.

 -  The REXX .CMD and text files for XFolder's installation.
    The files to be translated are in the "MISC" subdirectory.

 -  The SmartGuide (Warp 4) script used for the XFolder introduction.
    This (XFLDR001.SGS) is also in the "MISC" directory.

The "HTML2IPF" directory contains a valuable tool for converting
HTML files to the IBM (IPF) format. This will be described later.


Required tools:
===============

I am currently using IBM VisualAge C++ to develop XFolder. Although all
the source files in this package can be edited using any editor (because
they're all plain text files), you will need some IBM compiler to actually
compile the files. I have not tried EMX/GCC.

To be more precise:

 -  The make files in this package were written for IBM NMAKE, which comes
    with all the IBM compilers. I'm not sure these will work with other
    MAKE utilities. I'd be grateful for feedback.

 -  The message file (XFLDxxx.MSG) can only be created if you have any
    version of an OS/2 Developer's Toolkit (even 2.x should work),
    because you will need MKMSGF.EXE (see the respective chapter below).

 -  The same applies to the .INF and .HLP files: to build these, you
    will need IPFC.EXE from the Toolkit (see the respective chapter below).

If you do not have these tools, don't worry. You can still translate the
files and simply send them back to me, and I'll do the rest.


A note on distribution:
-----------------------

Please do not distribute XFolder NLS packages yourself. Since
I might update XFolder after you have finished your work on your
NLS version, XFolder might have trouble cooperating with your
files. Internal IDs might change and/or new features might be
added.

So if you have finished creating your NLS package, please contact
me, and I will put in on my homepage and upload it to Hobbes and
other places on the Internet. This seems like the best solution
to be, because I have a list of places which carry XFolder, and I
can update all the NLS packages myself when anything changes with
XFolder. This way, my homepage will always be the place to look
for up-to-date NLS packages.

Thus, when you're done translating, please zip up the complete
directory tree again and mail the ZIP file back to me. I will
give you loads of credits for your work wherever you want it,
but I need the sources back, so I can change things myself in
case a new XFolder version comes out or things don't work out
right.

Thanks!


The NLS DLL
===========

    The files herein contain everything neccessary to compile a resource
    DLL (XFLDRxxx.DLL, with xxx being your country code). The resource
    DLL contains strings, dialogs, and notebook pages.

    BTW: I'm really curious how "Snap to grid" sounds in your language. ;-)


    Neccessary preparations:
    ------------------------

    Most files in this directory carry a three-digit language code in
    their respective names; the files are prepared for English (language
    code 001).

    1)  For your language, you need to change all the filenames
        with "001" in their names to your country code (e.g. 039 for Italian).

    2)  You will also have to change the .DEF and .MAK files, which assume
        a country code of 001 at this point. Required changes are noted in
        the files themselves.

    Note that all the dialog ID's access the "dlgids.h" file in the NLS
    package main directory. DO NOT CHANGE anything in that file, or XFolder
    will get really confused.


    Files that need to be changed:
    ------------------------------

    --  xfldr001.def:   The module definition file.
                        Required changes are noted in the file itself.
    --  xlfdr001.mak:   Makefile for IBM NMAKE.
                        Required changes are noted in the file itself.
    --  xfldr001.rc,    These are the main resource files which need lots of
        xfldr001.dlg    changes. I've documented everything you need to change
                        in these files directly.
    --  xfldr001.txt:   This is the "source" file for the XFLDR001.MSG
                        file. You will need MKMSGF from the OS/2 Warp Toolkit
                        to convert this plain text file into a .MSG file.
                        See the notes in that file.


    Using a dialog editor:
    ----------------------

    If you open xfldr001.res with the dialog editor, you can also translate
    the dialogs without having to edit the .DLG file.

    When you then save the file, the .RES and .DLG files will be recreated.
    The .RC file remains untouched though.

    The dialog editor has a helpful "Translate mode" in its "Options" menu
    which disables a lot of menu items so you don't accidentally change dlg ID's.

    I don't know if you can use the URE editor also, I have not tried that.


    Recompiling the DLL:
    --------------------

    --  If you have any IBM C compiler, simply type "nmake xfldr001.mak" at the
        command prompt (replace 001 with your language code).
        Everything should work fine, since all the neccessary
        files are included. I don't know if the makefile works with other
        compilers.

    --  If you don't have IBM C, things get a bit more complicated. Since the
        resource compiler (RC.EXE) and the OS/2 Linker (LINK386.EXE) already
        ship with OS/2, you can try the following:
        1)  Open a command line in this "dll" directory and type
                rc -r xfldr001.rc
            which should create a new ".RES" file. Of course, replace "001"
            with your language code.
        2)  Then type the following:
                link386 /noi /noe /map /nol /align:16 xfldr001.obj,xfldr001.dll,,,xfldr001
            This should link the .RES file so that you get a new DLL.

    You don't HAVE to recompile the DLL. You can simply change the resource files
    and mail them back to me, I'll appreciate that too.
    Recompiling might be helpful for testing the DLL on your system though.


    Testing your new DLL:
    ---------------------

    Make sure you do not currently have your new language DLL selected on the
    "XFolder Internals" settings page, because if you do, the DLL is locked
    and cannot be replaced. Select "US English" instead, which will unlock the
    previously used DLL, and it can be deleted from the XFolder directory. Now put
    your new DLL into the BIN subdirectory and open the settings again; select
    your DLL and see if things work.


Directory "MISC"
================

    This directory contains files used by XFolder's installation script
    (INSTALL.CMD) plus the SmartGuide Script used for the XFolder
    introduction.

    --  INSTxxx.MSG (with "xxx" being your country code, which you need to
        change) is -- I'm sorry -- in a proprietary format. It's not difficult
        to understand though: The file is used by "XHELP.CMD" (in the XFolder
        package), which is capable of extracting single text messages in
        between the "<TOPIC>" and "</TOPIC>" tags in this file. The text
        between these tags is then displayed on the screen.

        What you need to do here is simply translate all the text which follows
        a "<TOPIC>" tag. The text is displayed "as is", and no formatting is
        performed; as a result, you must take care that no more than 80
        characters are contained in a line.

        You also should take care of the line breaks: it makes a difference
        in output whether a "</TOPIC>" end tag is found at the end of a line
        or at the beginning of a new line, because in the latter case, the
        line break is still printed to the screen.

        Just one more note: Do not change the keys mentioned in this file
        ("X", "Y", "N"), even if your language does not use "Y" for saying
        "Yes". Unfortunately, INSTALL.CMD relies on these keys. :-(

    --  CROBJxxx.CMD is a straightforward REXX script which creates the
        default XFolder Configuration Folder. Even if you don't know REXX,
        don't worry: you only have to change the strings on top of the file,
        which contain all the language-dependent things. Be careful with the quotes.
        Do not change anything else, because XFolder relies on it.

    --  SOUNDxxx.CMD is the REXX script which creates the neccessary INI
        entries for having the new XFolder system sounds in your "Sound"
        object. Only change the strings at the top of the file to your language.

    --  XFLDRxxx.SGS is a Warp 4 SmartGuide script to display the "Welcome"
        window after XFolder has been installed and the WPS has been restarted.
        I have no idea what the precise syntax for these files is (once again
        has IBM developed good software, but then lets it rot), but it seems
        to be some HTML-like syntax, except that the tags MUST be in
        lower case, or they won't work.


Directories "INF" and "HELP"
============================

    Again: These two directories only unzip properly on HPFS drives!!!
    Both the filestems and the extensions are too long for FAT.

    These directories contain everything you'll need to translate the
    sources for the ".HLP" and ".INF" files.

    You need however some OS/2 Developer's Toolkit to be able to create
    INF and HLP files.

    Please use the "MAKE.CMD" file on the top level of the XFolder source
    files to have the doc files created. This might take a while. You will
    first need to set a few environment variables on top of MAKE.CMD, which
    is documented in that file itself.

    You then have two alternatives for the translations:

    --  You can translate the ONE .IPF file in each of the INF and
        HELP directories directly, if you're familiar with the IPF source
        language, which is a proprietary IBM format (and which I don't like
        at all). You can then feed this .IPF file into the IPFC.EXE compiler
        to have the .INF and .HLP files created.

        This has the disadvantage that if certain panels change in future
        versions, you'll have no clue what parts changed in this single IPF
        file.

        Please change the text only. Do not change any resources, IPF tags,
        and especially not the resource ID's, or XFolder will not find its
        help panels any more.

    --  You can translate all the .HTML files and keep using the "MAKE.CMD"
        file to have the HTML files converted into a single .IPF file
        (using the HTML2IPF utility), which is then fed into IPFC also.

        This has the advantage that you'll only have to change some panels
        in future versions, of which I will keep track.

        The disadvantage is that HTML2IPF is slow.

        The "root" file in the "INF" and "HELP" directories, respectively,
        is called "XFLDRxxx.HTML", respectively, with "xxx" being your
        country code (which you should change in this one filename).

        To use HTML2IPF manually, open a command line in the INF or HLP
        directory (with XFolder ;-) ), and type:

            <path>\html2ipf xfldr001.html

        This will create a "XFLDRxxx.IPF" file (in the above example,
        XFLDR001.IPF). You can then run "ipfc XFLDRxxx.IPF" to compile
        a HLP file; add a "/INF" switch to produce an "INF" file.
        You must have the INF or HLP directory as your current directory,
        or HTML2IPF will tumble.

    If you don't have the Developer's Toolkit, there's no way you can
    actually produce the INF and HLP files. You will have to use Netscape
    or WebExplorer to view the help files, which of course are on many
    separate pages then. Begin viewing "XFLDRxxx.HTML" in the INF and
    HELP directories, respectively.

    In any case, mind these important notes:

    --  The (slightly awkward, I admit) structure of the files is the
        following, in both directories:
        -- "XFLDRxxx.HTML" is the "root" file;
        -- files beginning with "0" appear in the contents tree of the
           produced INF and HLP files;
        -- all other files are somwhere below in the INF/HLP structure.

    --  Do not change filenames! HTML2IPF sorts the IPF pages internally
        alphabetically according to the filenames, that's why I've
        implemented these strange naming conventions. I admit that since
        the structure has developed over time, it may not seem very
        logical to you, but it works. Changing things here will result
        in a lot of work, since all the links in the HTML files will
        have to be renamed also.
        Also, if you change the linkage of the HTML files, the resource
        IDs of the help panels will be altered, and XFolder will then
        get confused displaying the proper help panels.

    --  Within the HTML files, do not change ANYTHING within angle
        brackets ("<xxx>"). Translate ONLY the text outside of these.
        Even though some tags might not be good HTML style and the
        HTML files might not look pretty when viewed with Netscape,
        certain tag combinations (especially the <BR><LI> combinations)
        are neccessary to make the pages look good for IPF.

    --  Don't forget to translate the page titles (in between the
        <TITLE> tags). I've forgotten this many times...

    --  There are a number of files in the HLP directory which seem
        pretty useless. These are neccessary however in order to
        guarantee a certain sequence of the help panels in the
        resulting HLP file, on which XFolder relies for calling
        a certain help panel. I don't quite understand myself anymore
        how this order works, but it does, so I don't care. ;-)

    --  I do not recommend translating EVERYTHING for the INF book.
        I have done the German translation myself,
        and I think that the "Revision history" section makes no
        sense translating, because it is frequently updated and
        NLS versions didn't exist for the older versions anyway.
        Also, the "XFolder Internals" pages apply to programmers,
        which need to know English anyway, because otherwise they
        won't find their way through the required Toolkit docs
        either. So I think you can save yourself some work there.


    Images, Screenshots
    -------------------

    The images in both the INF and HELP directory are always available
    in both GIF and uncompressed OS/2 1.3 BMP format. The reason for
    this is that HTML does not support BMP, and IPF does not support
    GIF. :-( HTML2IPF is very comfortable in this respect: it will
    automatically convert all GIF images to BMP format every time it
    finds an <IMG> tag, but only if no BMP file of the same filestem
    was found (see HTML2IPF.INF for details).

    The image conversion program which HTML2IPF requires is specified
    in line 20 of HTML2IPF.CMD. The original had Image Alchemy in here,
    I have changed it to "GBMSIZE", which is part of the freeware
    "Generalized Bitmap Module" (GBM) package available at Hobbes.

    --  If you don't have GBMSIZE on your PATH, you can add the path to
        this line.

    --  If you wish to use a different converter, specify it here. Be
        careful though: IPFC only supports UNCOMPRESSED OS/2 1.3 bitmaps
        (see HTML2IPF.INF). Do not compress them. This is annoying, because
        IPFC's own image compression is totally outdated, but it's a fact.

    I'd be very grateful if you could create your own screenshots
    for the online documentation, because I own German versions of OS/2
    and for your NLS package, screenshots of your language are
    preferrable.

    I have used the following settings for the screenshots:

    Fonts used:
        Titlebars: Humanist 521, 13 points (available on the
                   CorelDraw 4 CD in Type 1 format)
        All the other fonts are set to 9.WarpSans.

    CandyBarZ installed, colors:
        Active:     top 191/0/0, bottom 52/0/0
        Inactive:   top 160/160/130, bottom 40/40/40

    XFolder installed. ;-)

    Now, if you create your own screenshots, save them as GIFs with the
    exact filenames of the originals (e.g. "trunc.gif"); you must then
    DELETE the respective BMP file, because HTML2IPF will only call the
    image converter for BMP if no BMP file of the same name exists.


    Testing your new HLP/INF files:
    -------------------------------

    Before compiling the .IPF to the .HLP/.INF files, you should make
    sure that the target file is not locked by the WPS.
    With .INF files, that's easy: simply close it if it's open.
    With .HLP files, you have to keep in mind that the WPS keeps these
    files locked even after you've closed a help panel window. However,
    the WPS only keeps one .HLP file locked at a time, so in order to
    unlock the XFolder .HLP file, simply open a default WPS help panel,
    e.g. by selecting "Extended Help" for the Desktop window.
    You can then copy the new XFolder .HLP file to the XFolder HELP
    directory. (MAKE.CMD will do this automatically.)


"html2ipf"
==========

    The "Tools" directory contains the very valuable "HTML2IPF" tool by
    Andrew Pavel Zabolotny. This REXX script is capable of creating a single
    .IPF file from a list of linked HTML files, which can then be fed into
    IBM's IPFC.EXE for creating .HLP and .INF files.

    I have slightly modified this tool (see notes below).

    Even if you don't know what I'm talking about, in this directory, you
    need to open HTML2IPF.CMD and change three, maybe four things:

    --  In line 27, translate the 'Resources on the Internet' string.
    --  In lines 28-31, translate the string beginning with "This chapter contains...";
        translate every line, but do not mess with the "'||'0d0a'x," codes
        and such.
    --  In lines 34/35 translate the 'Click below to launch [code] with this URL:'
        string, but do not change the code in the middle.
    --  In line 20, change the image converter; this is thoroughly explained in
        the "Images" section above.


    Additional information (not obligatory)
    ---------------------------------------

    I have included HTML2IPF.INF, which describes how the tool works. You
    need not bother with this though, because everything is already set up
    properly.

    I have changed HTML2IPF.CMD in a few places to allow for IPF window
    positioning and certain extra character formatting. These changes are
    only documented here, in case you're interested -- you will NOT find
    these changes in the INF file (you don't have to know this, just if
    you're curious):

    --  The <HTML> tag has new attributes: XPOS= and YPOS= work just like
        IPF's "x" and "y" tags; WIDTH= and HEIGHT are the same as in IPF.
    --  Added the strings described above to global variables for NLS.
    --  The <A> tag accepts a new "AUTO=" attribute, which works just like
        "HREF=", but automatically opens and closes the window (this is, for
        example, used on the "Introduction" page of the Online Reference).
    --  The <CITE> and </CITE> formatting tags are now set to use a
        non-proportional font, which is used extensively.
    --  Some formatting changes (<UL>, <BR>, <B> etc.).
    --  HTML2IPF now removes indenting spaces at the beginning of lines
        because these would all appear in the INF/HLP files, while HTML
        ignores them. (New with V0.81).

Hey, thanks for reading all this. And thanks again for your support...
and now, have fun translating!

