                           Documentation of

                                 mapS


                   Version 1.2 of February 9, 2001
                     (C) 2000, 2001 Gerald Dietze
               P.O. Box 1401   70810 Korntal   Germany

                               Contents

Contents
========

 1  mapS in general
    1.1  Whom is mapS interesting for?
    1.2  Regarding rights and limitations in the demo-version
    1.3  Hard- and software-requirements
    1.4  ==> Registration <==
    1.5  I have the codes - How to register?
    1.6  Source for current versions
    1.7  Contact the author
    1.8  The software-package
    1.9  Thanks to...

 2  The File-formats
    2.1  The format of the Address-files (*.ADR)
    2.2  The format of the mail-text-files (*.TXT)
    2.3  Compatibility of files

 3  Installation and operation
    3.1  Installation
    3.2  The operation of mapS
    3.3  The Online-Help

 4  past and future
    4.1  mapS history
    4.2  Future



1  mapS in general
******************


1.1  Whom is mapS interesting for?
==================================


mapS is interesting for everybody, who

    is using the STinG-compatible Mailer MyMail of Erik Hll

    wants to send massmail mit variable mailtext


1.2  Regarding rights and limitations in the demo-version
=========================================================

                  mapS (C) 2000, 2001 Gerald Dietze
                         All rights reserved

     Dietze Soft International - P.O. Box 1401 - D-70810 Korntal

            Copyright and limitations in the demo-version

mapS is shareware. As only limitation compared to the registered
Version, the program is printing out an information text in every mail
that tells everybody that you were using an unregistered version of
mapS to create this mail.
The codes to make mapS become a licensed version are available from
the author and they must never be given away to third persons because
one can create as many licensed versions under your name as he wants.
Copying the non-licensed version is allowed and appreciated, but the
original archive has to be published always.
Program- and documentation-files may not be changed.
Abuse will be prosecuted!
It is not allowed to send unsolicited (whether commercial or not) e-
mail with this program.


                        Exclusion of liability

This software was programmed carefully and tested innumerable times.
Anyway, errors can never be excluded completely. I'm neither taking
explicit nor implied any juristical responsability or liability for
damage caused by the use of mapS. There's no warranty that the
hypertext mapS.hyp and mapS.txt are complete and correct.
By use of mapS you are declaring that you are yourself responsible for
the mails you create and send with mapS.

                              Trademarks

In this documentation, trademarks are mentioned but not marked as
trademarks. By the lack of remark it can't be implied that a name is
free of rights.





     mapS is written in OMIKRON.BASIC by the use of KLib-Library.





1.3  Hard- and software-requirements
====================================

         Hard- and software-requirements for the use of mapS:

    All computers that are running or emulating a TOS-compatible
     multitasking-system. It's not working under single-TOS. I have
     tested it under MagiC! 6.

    Graphics has to be at least ST high res (640*400). The number of
     colours isn't important.

    A text-editor, that can save the TAB-character (ASCII 9), e.g.
     qed.

    Of course MyMail by Erik Hll





1.4  ==> Registration <==
=========================

mapS is shareware and of course I am happy about every registration I
get.

The registration-fee for mapS is only

                                3 EUR

To order the registrieration-key there are only the following
possibilities:

    by E-Mail (see "Contact the author") for Europe
      tranfer to the account:
          Gerald Dietze
          Account No. 347 36 72
          Landesbank B-W (BLZ 600 501 01)
     The Codes will be sent by e-mail after cash arrived on my
     account.
    by mailing (see "Contact the author") the cash (US$ 3 for
     America) to my address.
      Please give me also an e-mail with the required data.
     The Codes will be sent by e-mail after cash arrived by mail.

Don't forget to give complete Name and e-mail-address on account-
transfers, this Data is required to generate the codes.
Please send the following order-form by e-mail to my address:



----------------------------------------------------------------------


     Dietze Soft International
     -Gerald Dietze-
     P.O. BOX 1401
     70810 Korntal-Mnchingen
     Germany

     E-Mail: DSI@gerald-dietze.de


     Betr.: DSI mapS

     Please send the registration key for mapS to my
     E-Mail-Address ______________________________

     ( ) I have transferred the amount of 3 EUR to your account.
     ( ) I have mailed 3 EUR / US$ 3 to your postal address.

     My address:

                      Name    :_____________________________

                      Street  :_____________________________

                      Zip/City:_____________________________

                      Country :_____________________________






1.5  I have the codes - How to register?
========================================

A unregistered Version of mapS can be licensed with the keys by the
following:

Open mapS.prg and choose the button "R" in the info-dialog. Enter name
and registration key and confirm "OK". The registration was successful
when the "R"-button in the info-dialog isn't selectable any more.
Giving the keys away or publishing them is strictly prohibited!



1.6  Source for current versions
================================

                     Download of current versions

    In the WWW:
     http://www.gerald-dietze.de/dsi.html





1.7  Contact the author
=======================

                        Contact the author...

I am best reachable by my e-mail-address. By postal mail the reply can
take a (long-lasting) while. In this case only mail with prepaid
postage can be answered, sorry.

    Internet: DSI@gerald-dietze.de
    Snail-Mail:
     Gerald Dietze
     Postfach 1401
     70810 Korntal
     Germany





1.8  The software-package
=========================

                    The most important files are:

 MAPS.PRG: The program mapS itself.



Files in German language:

 \GERMAN\MAPS.RSC: German resource-file.
 \GERMAN\MAPS.SYS: A required system-file.
 \GERMAN\MAPS.HLP: The Bubble-Help-file.
 \GERMAN\HANDBUCH\ASCII\MAPS.TXT: The handbook as ASCII-text.
 \GERMAN\HANDBUCH\STG\MAPS.HYP: The handbook as ST-Guide-hypertext.
 \GERMAN\HANDBUCH\STG\MAPS.REF: The REF-file for HYP.
 \GERMAN\HANDBUCH\HTML\MAPS.HTM: The handbook as HTML-documents.
 \GERMAN\BEISPIEL\*.*: Example-files.



Files in English language:

 \ENGLISH\MAPS.RSC: English resource-file.
 \ENGLISH\MAPS.SYS: A required system-file.
 \ENGLISH\MAPS.HLP: The Bubble-Help-file.
 \ENGLISH\HANDBUCH\ASCII\MAPS.TXT: The handbook as ASCII-text.
 \ENGLISH\HANDBUCH\STG\MAPS.HYP: The handbook as ST-Guide-hypertext.
 \ENGLISH\HANDBUCH\STG\MAPS.REF: The REF-file for HYP.
 \ENGLISH\HANDBUCH\HTML\MAPS.HTM: The handbook as HTML-documents.
 \ENGLISH\EXAMPLE\*.*: Example-files.




 LIESMICH.TXT: file that tells about recent changes (German).
 README.TXT: file that tells about recent changes (English).
 MAPS.INF: Is written after the first execution of mapS.
     It contains filepaths, mail-subject and registration key.





1.9  Thanks to...
=================

    Erik Hll for the development of MyMail.
    Karsten Ldersen for the great GEM-Library KLib and beta-testing.
    Ulf Ronald "dlanor" Andersson for beta-testing.





Erik Hll
---------

    Projects:
      MyMail: The Mailer for STinG and STiK
    Contact:
      Internet: erikhall@tripnet.se
      WWW: http://www2.tripnet.se/~erikhall/main.html





Karsten Ldersen
----------------

    Projects:
      KLib: The extensive GEM-Library for OMIKRON.BASIC.
      KLed: The source-code-editor for OMIKRON.BASIC.
      Library-Maker continuing the development of the Lib-Makers for
          OMIKRON.BASIC.
    Contact:
      Mausnetz: Karsten Ldersen @ HH





Ulf Ronald "dlanor" Andersson
-----------------------------

    Projects:
      STinG: Further development of Peter Rottengatter's network layer
          STinG.
      BetaDOS: An improved MetaDOS-replacement.
      LaceScan: Increases screen-resolution on STs and STEs.
    Contact:
      Internet: dlanor@ettnet.se





Markus Kohm
-----------

    Projects:
      Mungojerrie: Sending mixed e-mail with CAT.
      Jelly Cat: CAT-module: block protection.
    Contact:
      Mausnetz: Markus Kohm @ KA2






2  The File-formats
*******************


2.1  The format of the Address-files (*.ADR)
============================================

                      The address-files (*.ADR)

In every address-file, variable-names are defined in the first line.
Every variable should begin with the "$"-char and the following string
should be written in upper case, because it is case-sensitive. The
defined variable-names are separated by a TAB-char, in the following
signed as [T]. The first variable is always the recipient's address
and it has always to be defined as $ADR, the rest of the variables can
be defined free. Only rule: All variable-names must be different and
must not be part of each other. For example $NAME and $NA are not
valid in the same address-file. If $NA is replaced by "Bill" it could
happen that "BillME" appears in the Mail instead of "Bill"!

In the following lines there are the data-sets, elements also
separated by [T]. For every line, there will be generated a Mail,
later. The variable-name at the n-th position in the first line will
be replaced by the n-th value in the current line. Sounds maybe
somewhat complex, but it's easy, as you can see looking at an example:
You want to invite some people personally by a roundmail to your
birthday-party.

You are creating the following file:

$ADR[T]$NAME
friend1@birthday.net[T]Andy
friend2@xyz.com[T]Martin
blabla@abc.org[T]Christine


It's important to chose an editor-program with the ability of saving
the [T]-char correctly.
It's not said that you want to send the mail to everybody mentioned in
the address-file. Recipients you want not to be sent the mail, can be
excluded by the control-words $OFF and $ON. Any of the words has to be
alone in a line and has to start in the first column.

If you e.g. want to exclude Martin from your invitation, you'll have
to change the file to the following, if you don't want to delete him
from the list:

$ADR[T]$NAME
friend1@birthday.net[T]Andy
$OFF
friend2@xyz.com[T]Martin
$ON
blabla@abc.org[T]Christine

Of course, excluded blocks can have more than one address only.

Since V1.1, mapS has a mighty additional function. Everybody knows the
problem that one wants to send mails to different topics to the same
person. In ancient times you needed to have different address-files
with the same address in any of it. When addresses of receivers
changed, you had to check and change any address-file. In the new
version of mapS you can keep aoll your addresses in one file. Therefor
you have to make another Variable with the fixed name $DISTRIBUTION in
your address-file. For different mail-lists with different topics, an
alphabetical char is given to each. The choice for any data set is
made by writing the alphabetical chars as values into the place of
$DISTRIBUTION, if some should get a mail of that topic. the choice of
receivers is done during run-time of mapS by entering the
abbreviation-char of the wanted receiver-group under "receiver" in the
main dialog.

Also an example:


$ADR[T]$NAME[T]$DISTRIBUTION
friend1@birthday.net[T]Andy[T]f
colleague@xyz.com[T]Martin[T]fc
blabla@abc.org[T]Christine[T]c


The groups of receivers are specified as:
f: friend
c: colleague

To send a mail only to colleagues, you enter "c" into the "receiver"
field of mapS. For sending a mail to friends and also colleagues, you
enter "cf". In this case the mail is sent to all of the three.



2.2  The format of the mail-text-files (*.TXT)
==============================================

                     The mail-text-files (*.TXT)

For sending a personalized mail to people in a list it's enough to
write a text containing the variable-names as replacements at the
position you wish to use them, i.e.:


Dear $NAME!
I'd like to invite you to my birthday-party on Sun. 12/24, 7.30 pm at
my flat.
Regards,
Gerald



recipient address: $ADR



2.3  Compatibility of files
===========================

If you know the mailer CAT for the German Mausnet, you might know the
mix-mailer module Mungojerrie (see "Markus Kohm").
The idea for mapS was inspired by Mungojerrie. So I kept the *.ADR and
*.TXT file-formats compatible to it that everybody can use his old
Data without changes!



3  Installation and operation
*****************************


3.1  Installation
=================

                             Installation

At first, copy the complete MAPS-folder to any partition you like. If
you don't want to use the default installation German, you can install
mapS in English language:
There are two folders, named "GERMAN" and "ENGLISH". Choose the folder
of the language you want to choose and copy the whole content one step
out of this folder, that means in the directory, where maps.prg is
located.
If you want to use ST-Guide as Help-System, copy mapS.hyp and mapS.ref
into your Hypertext folder or the root where mapS.prg is located.
Run mapS.prg.


3.2  The operation of mapS
==========================

                        The operation of mapS

mapS is easy to handle and has just got a main-dialog-window, a menue
bar does not exist.
If you have installed Bubble-Help, you can get an information to any
dialog elemnt by clicking the right mouse key.



+-----------------------+----------------------------------------------------------------------------+
| Dialog-field/Button   | explanation                                                                |
+-----------------------+----------------------------------------------------------------------------+
| Addresses             | Select the address-file to use.                                            |
+-----------------------+----------------------------------------------------------------------------+
| Mailtext              | Select the mail-text you want to send.                                     |
+-----------------------+----------------------------------------------------------------------------+
| Subject               | Enter subject of the mix-mail here.                                        |
+-----------------------+----------------------------------------------------------------------------+
| MyMail                | For proper operation, you have to select the path where MyMail is located. |
+-----------------------+----------------------------------------------------------------------------+
| Info                  | Info-dialog and registration                                               |
+-----------------------+----------------------------------------------------------------------------+
| Help                  | Opens this HYP-page.                                                       |
+-----------------------+----------------------------------------------------------------------------+
| Quit                  | Saves settings and leaves the program.                                     |
+-----------------------+----------------------------------------------------------------------------+
| Print Mails to MyMail | Appends the mix-mails to qmail.txt.                                        |
+-----------------------+----------------------------------------------------------------------------+

                Table 1: Operation of the main-dialog


When you have started the output of the mails, in the first run mapS
checks, if every data-set of the address-file has the right number of
elements. If the program recognises an error it will be alerted and no
output will be made. With $OFF and $ON (see "The format of the
Address-files (*.ADR)") encapsulated parts are simply ignored.


3.3  The Online-Help
====================

mapS offers two possibilities:

 ST-Guide: To use that help, you must have installed the ST-Guide
     Hypertext-System as help-system. MAPS.HYP and MAPS.REF can either
     be located in the root of MAPS.PRG or in the hypertext-folder.
 Bubble-Help: If you have installed Bubble-Help, you can get a short
     help text on any dialog-element by pressing the right mouse-
     button.







4  past and future
******************


4.1  mapS history
=================

    V1.0 of 04/05/2000 (see "History V1.0")
    V1.1 of 08/24/2000 (see "History V1.1")
    V1.2 of 02/08/2001 (see "History V1.2")





History V1.0
------------

    Bugfixes:

        - None, first publication of mapS

    News:

        - Everything, first public Version





History V1.1
------------

    Bugfixes:

        - None, no bugs known

    News:

        - It's possible to make receiver-groups. From now on, no
          different files for different receiver-groups are needed any
          more, one with all addresses is enough.





History V1.2
------------

    Bugfixes:

        - Now, the program works without problems parallel with STinG
          and its dialer.
        - There was a mistake in the file-path management
        - The main dialog-window was opened into the menu-bar,
          sometimes
        - Because of a mistake in the English RSC-file, the ST-Guide
          hypertext could not be used as online help.
        - In the English Version, pressing the <HELP>-key did not open
          the ST-Guide description in any dialog.

    News:

        - nothing new...





4.2  Future
===========

                                Future

The intensity of further development of mapS depends also on the
number of registrations and the feedback I get from users. I am happy
about all suggestions although I can't give a guarantee to implement
them all.
Anyway, let's see what prospects I'll have...




