Auto-configuration of Pegasus Mail for Windows v2.53 and later
Pegasus Mail System, Copyright (c) 1990-97, David Harris.
----------------------------------------------------------------------

Starting with the release of Pegasus Mail for Windows v2.53, two versions
of each Pegasus Mail release will be made available at release time. The
first version is the standard end-user version, while the second version
is intended especially for distribution by ISPs and Network Administrators.
This document describes the ISP version, and how ISPs and Network Adminis-
trators can use it to provide customised and/or simplified installation and
configuration for their users.

The ISP versions of Pegasus Mail will be standard distribution archives
with the addition of a special Pegasus Mail extension called WPMSETUP.
WPMSETUP is designed to auto-load on the very first occasion a user runs
Pegasus Mail for Windows. It can set any preference or operating field
within the running copy of WinPMail and can prompt for user input as
required. WPMSETUP uses a script file called WPMSETUP.DAT to determine
the form of the settings it needs to change: WPMSETUP.DAT can be located
in any of the following places, searching in the order shown:

   * In the directory from which WINPMAIL.EXE was run.
   * In the \WINDOWS directory
   * In the \WINDOWS\SYSTEM directory
   * On the PATH

If WPMSETUP.DAT cannot be found in any of these locations, WPMSETUP will
prompt the user to enter the location of the file, defaulting to "A:\".
ISPs and Network Administrators can also supply a bitmap file that
WPMSETUP will load and present in its dialogs: this both promotes the
tight integration between the ISP and Pegasus Mail and also enhances the
user's sense of the professionalism of the installation process. Bitmaps
should be 140x120 pixels in size or smaller and should be 16-colour
(Windows cannot display 256 colour bitmaps properly without special
third-party code: in the interests of size and space, we decided to omit
that code from WPMSETUP).

The ISP versions of WinPMail are set up on the assumption that the ISP or
Network Administrator will give his users a diskette containing the
WPMSETUP.DAT file needed to auto-configure their systems. In the event
that this is not a satisfactory way of doing things in any given
instance, it is also possible to repackage the WinPMail distribution
archive so that it contains an appropriate WPMSETUP.DAT ready-to-run. For
information on repackaging the WinPMail archive files, please see the
file SETUP.TXT supplied with this kit.

WPMSETUP is driven by a simple scripted file that looks rather like a
standard Windows INI file. The remainder of this document details the
format and layout of this file, and describes its capabilities. This ISP
setup kit also contains a number of sample WPMSETUP.DAT files that ISPs
and Network Administrators can use as the basis of their own setup files.


------------------- Cut here for sample WPMSETUP.DAT file ------------

;
;  WPMSETUP.DAT
;  Sample ISP Setup file for Pegasus Mail for Windows v2.53 and later.
;
;  This file contains instructions for both the WinPMail Setup program,
;  and for the WinPMail WPMSETUP Extension, and is intended to be used
;  by service providers and network administrators to provide default
;  values for Pegasus Mail's setup and preferences.
;
;  The file looks like a Windows INI file to some extent, but is actually
;  handled differently; It is divided into sections, where each section
;  has a heading like this: "[Section-name]" on a line of its own. The
;  sections that can be found in this file are:
;
;      [Setup]   - instructions to the WinPMail setup program
;      [Prolog]  - text for a preamble dialog
;      [Prompt]  - create a dialog to prompt the user for information
;      [Script]  - instructions for setting up WinPMail's preferences
;
;  All the sections are optional - so, it is legitimate to have only a
;  "[Script]" section if you don't need to prompt the user for any data.
;
;  1: The [Setup] Section
;  The [Setup] section is read by the WinPMail setup program if WPMSETUP.DAT
;  is in the same directory as SETUP.EXE; it can also be placed in SETUP.DAT,
;  but WPMSETUP.DAT is used preferentially if it is present. The [Setup]
;  section can contain the following commands:
;
;      Set WinPMail directory = <d:\path>
;        - Set the location where WinPMail will be installed
;          (the default is C:\PMAIL)
;      Set WinPMail directory prompt = <Y|N>
;        - If 'Y', then setup will not ask the user to enter the
;          location where WinPMail should be installed and will use the
;          current or default value instead.
;      Set NetWare = <Y|N>
;        - If 'N', then setup will not offer the choice of installing
;          in NetWare mode and will force installation in standalone mode.
;      Set US Dictionary = <Y|N>
;        - If 'Y', Setup will install the US English dictionary as
;          the default for the spelling checker, otherwise the UK English
;          dictionary will be the default. If this option is present,
;          setup will not prompt the user for the choice.
;      Set Mailto Handler = <Y|N>
;        - If 'Y', Setup will install WinPMail in the Registry as the 
;          default handler for MAILTO: urls, which will allow it to act
;          as the mail front end for MS Internet Explorer. There is
;          usually no reason to set this to 'N'.
;      Set copy files = <Y|N>
;        - If 'N', setup will default to not copying the WinPMail program
;          files on its final setup screen.
;      Set create group = <Y|N>
;        - Set the default value of the control in the final setup dialog
;          that determines whether or not distribution files are copied.
;      Set manifest check = <Y|N>
;        - Tells setup whether or not to verify that all the files that
;          should be present actually are present. If set to 'N', no check
;          will be done but file copying will not be possible.
;
;  2: The [Prolog] Section
;  This optional section allows you to put up an initial informational
;  dialog prior to entering the prompt screen. The section should contain
;  three lines of text - a title and two descriptive entries. If present,
;  the prolog dialog is displayed showing the text you provide and your
;  bitmap (if any). The user proceeds to the prompt screen by clicking
;  on a "Next >" button.
;
;  3: The [Prompt] Section
;  This section allows you to create a dialog that the WPMSETUP Extension
;  will present to the user prompting him or her for information. You can
;  prompt for up to nine separate pieces of information, then substitute
;  that information into any preferences field later when the [Script]
;  section is processed. The [Prompt] section can contain from 1 to 9
;  commands in the following format:
;
;     prompt <T|P|C> <"Prompt text"> ["Default"]
;        -  "T" means to present the item as a text field
;        -  "P" means to present the item as a password field
;        -  "C" means to present the item as a checkbox
;        -  "Prompt text" is a short string describing the field, and
;           is used as a caption for the associated control.
;        -  "Default" is an optional default value for the entry.
;
;  The WPMSETUP extension will create a dialog based on the "prompt"
;  statements in the file and allow the user to edit them. The value
;  entered by the user in response to each prompt statement is stored
;  in the internal variables v1 through to v9, in the order in which
;  the prompt statements appear in the file.
;
;  4: The [Script] Section
;  This section is processed after the WPMSETUP Extension has prompted
;  the user to enter the information requested in the [Prompt] section.
;  It can contain the following commands:
;
;     set <preference_variable> = <value>
;       - Set an internal WinPMail preferences or configuration string
;         with the data in "value". See below for a list of the possible
;         "preference_variables".
;     mkdir <path>
;       - Create a directory
;     copy <sourcefile> <destfile>
;       - Copy a file
;     write <filename> <string>
;       - The string "string" is appended to the file <filename>. If the
;         file does not exist, it is created. Both the filename and the
;         string can contain substitutions. This command is a handy way
;         of creating signature files (for instance, INETSIG.PM in the
;         user's home mail directory, for Internet mail).
;     run <commandline>
;       - Run a program; "commandline" is the command string passed to
;         the Windows "WinExec" function - it may be a DOS or a Windows
;         program and may have commandline parameters.
;
;  Substitutions: you can replace any variable value in the [Script]
;  section with user-supplied or system-level information using 
;  substitution strings. If you have ever used a Pegasus Mail gateway,
;  then these substitutions should be mostly familiar to you already.
;  The following substitutions are possible:
;
;  When this is seen...    This is substituted
;  -------------------------------------------------------------------
;     ~n                   the user's username in its simplest form.
;     ~8                   user's object name truncated to 8 chars
;     ~d                   a random integer, expressed as 4 hex digits
;     ~%name%              the value of environment variable %name%
;     ~p                   the user's personal name preference
;     ~a                   the directory where WINPMAIL.EXE is located
;     ~h                   the current user's home mailbox
;     ~w                   the current user's new mailbox
;     ~vX                  the value of variable "X" (0 < x < 10)
;     ~~                   a single tilde (~).
;
;  So, for example, if you have the line:
;
;     set Alternative From: field for message = ~8@~v1
;
;  Then if the current user's username is "peter" and the user has been
;  prompted for a domain name in variable #1, entering "foo.bar.com",
;  then the string will be set in his profile as "peter@foo.bar.com"
;
;  Preference variables: The [Script] section's "set" command expects
;  the name of an internal variable to be set by the command: this can
;  be given in one of two ways:
;
;     1: You can use the long name of the variable, which is identical to
;        the text found in PMAIL.INI representing the setting. You need
;        only use enough characters from the long name to identify the
;        variable uniquely - so, for instance, the preferences variable
;        "Tab width in message editor (0-disable)" can be abbreviated to
;        just "Tab width" if you wish.
;     2: You can use a numeric value for the variable.
;
;  So, the following three strings all have the same effect:
;
;     set Folder for copies to self = COPYSELF
;     set Folder for copies = COPYSELF
;     set 5 = COPYSELF
;
;  While you can set practically any program setting from the [Script]
;  section, you should normally be selective - most items in Pegasus Mail
;  have sensible default values and you should alter only those things
;  that actually need specific tailoring. Items not accessed by a "Set"
;  statement in the [Script] section are not touched at all - they retain
;  their current value. This ability to set items selectively makes the
;  WPMSETUP extension useful for propagating changes at any time, since
;  the user can always select it from the "Extensions" submenu of the
;  WinPMail "Tools" menu.
;
;  The following variable names (and their corresponding numeric values)
;  are recognized by the Setup extension
;
;  Personal name                                1
;  Default right margin                         2
;  Home mailbox location                        3
;  Copy to self                                 4
;  Folder for copies to self                    5
;  Commenting string                            6
;  Folder sort order                            7
;  Default reply-to address                     8
;  Reply field settings                         9
;  Edit mail before forwarding                 10
;  MHS mailbox name                            11
;  Request confirmation of reading             12
;  Startup directory                           13
;  MHS Application directory                   14
;  Scan MHS application directory              15
;  Open new mail folder at startup             16
;  Save deleted messages until exit            17
;  Prompt to select copy to self folder        18
;  Leave read mail in newmail folder           19
;  Address book sort order                     20
;  Require password at startup                 21
;  MHS address                                 22
;  Use MIME features                           23
;  Default MIME character set                  24
;  Encrypt copies-to-self of encrypted mail    25
;  Don't confirm message deletion              26
;  Enclose attachments instead of separating   27
;  Noticeboard sort order                      28
;  Lines to scan for message enclosures        29
;  Button panel mode                           30
;  Button panel is closed                      31
;  Button panel window rectangle               32
;  New mail folder window rectangle            33
;  Default signature for outgoing mail         34
;  Request confirmation of delivery            35
;  Application window frame is maximized       36
;  Application window rectangle                37
;  Editor window default width and depth       38
;  Reader window default width and depth       39
;  Font to use in message reader               40
;  Font to use in message editor               41
;  Font to use in folder browser               42
;  Font to use for printing                    43
;  Offer advanced reply options                44
;  Top/bottom margin for printing              45
;  Left/right margin for printing              46
;  Local user list window rectangle            47
;  Reformat hard line breaks in replies        48
;  Printer device name                         49
;  Printer driver name                         50
;  Printer port                                51
;  Tab width in message editor (0-disable)     52
;  Logged-in user list window rectangle        53
;  Save desktop state between sessions         54
;  Wrap long lines in message reader           55
;  Built-in POP3 transport options word        56
;  Don't autoload WINSOCK.DLL if found         57
;  Seconds between POP3 new mail checks        58
;  Seconds between regular new mail checks     59
;  Secondary organization name                 60
;  Timezone for internal transport             61
;  Refuse confirm-read requests (internal)     62
;  Telltale window mode                        63
;  Telltale window control word                64
;  Location of TLC of telltale window          65
;  DList Manager window rectangle              66
;  Noticeboard Manager window rectangle        67
;  Header printing setting                     68
;  Extensions manager window rectangle         69
;  WAV file for new mail sound alert           70
;  Folder manager window rectangle             71
;  Omit message headers when replying          72
;  Use custom header when replying             73
;  Custom header format string                 74
;  Allow 8bit MIME data (!discouraged!)        75
;  Font to use in folder manager window        76
;  Quick folder definition                     77
;  Quick folder operating flags                78
;  MHS directory service window rectangle      79
;  Use system colours                          80
;  Display hot URLs in reader                  81
;  Web Browser Commandline                     82
;  Message reader format options               83
;  Message editor format options               84
;  Message editor autosave interval            85
;  Default settings values                     86
;  New mail folder column widths               87
;  Combined multipart reader rectangle         88
;
;  Host where POP3 mail account is located   1001
;  POP3 mail account (username on host)      1002
;  Password for POP3 mail account            1003
;  Delete downloaded mail from host          1004
;  Largest message size to retrieve          1005
;  Directory to place incoming POP3 mail     1006
;  Transport control word                    1007
;  SMTP relay host for outgoing mail         1008
;  Search mask to locate outgoing messages   1009
;  Alternative From: field for message       1010
;  TCP/IP timeout value (seconds)            1011
;  TCP/IP server port                        1012
;  TCP/IP SMTP server port                   1013
;
;  Bitmaps:
;  You can include your own Bitmap in the WPMSETUP windows by creating
;  a 16-colour version of your logo, 140x120 pixels or smaller (WPMSETUP
;  will centre the bitmap if it is smaller) and placing it in the same
;  location as WPMSETUP.DAT under the name WPMSETUP.BMP. If you do not
;  provide a bitmap file, WPMSETUP will use a Pegasus Mail bitmap by
;  default.
;

[Setup]


[Prolog]
Welcome to the Foo-ISP Setup Wizard.
This wizard will prepare Pegasus Mail for use with Foo-ISP's services.
Please locate your information sheet then click Next to continue.


[Prompt]
prompt T "Enter your personal name"
prompt T "Enter your username" "Jbloggs"
prompt P "Enter your password"
prompt C "Delete downloaded mail"


[Script]
mkdir c:\pmail\foobar\mail
set Personal name = ~v1
set Host where POP3 = urania.pmail.gen.nz
set POP3 mail account = ~v2
set Password for POP3 mail account = ~v3
set Delete downloaded mail = ~v4
set Largest message size = 1024000
set SMTP relay host = calliope.pmail.gen.nz
set Alternative From: field for message = ~v2@pmail.gen.nz
set TCP/IP timeout value = 150
set TCP/IP server port = 110
set TCP/IP SMTP server port = 25
set Save deleted messages = 1
set 19 = Y
set Don't confirm message deletion = Y
set Lines to scan = 120
set Font to use in message reader = Arial, 16, 0
set Font to use in message editor = MS Serif, 16, 0
set Font to use in folder browser = MS Sans Serif, 13, 0

