+--------------+
| REQUIREMENTS |
+--------------+

  In order to make use of the xisp package, you need to have ppp-2.2.0f
  or newer properly installed on your system. You also need to configure
  your modem for verbose result codes (this can be done, e.g. for a US
  Robotics Sportster, from within xisp by adding the "V1" command to the
  modem init command - details below), and if possible, for reporting
  your true connection speed rather than the computer-modem connection
  speed (i.e. the DTE<->DCE interface speed). Connection must be reported
  via a 'CONNECT xxxxx' string where 'xxxxx' is the speed string, and a
  busy phone status must be indicated by the string 'BUSY'. Since version
  2.5, the connection string is user modifiable, e.g., strings like
  'CARRIER xxxxx' can also be accommodated.

  To compile and install this package from the source distribution, you
  need a properly installed X11R6 (XFree86-3.1.2 for i386 Linux) or newer,
  as well as the forms library (XForms GUI by T.C. Zhao and Mark Overmars)
  version 0.88 or later. You can get a copy of this library at:

                   http://bloch.phys.uwm.edu/xforms or
                   http://bragg.phys.uwm.edu/xforms

  You'll also need a copy of the XPM library (libXpm version 3.4f or later),
  if you don't have it already; get this from your favorite public FTP site.


+---------+
| GENERAL |
+---------+

  The xisp package implements a user-friendly interface to pppd/chat
  and provides maximum feedback from the dial-in and login phases on a
  browser screen, as well as a manual login terminal window. It also
  provides greater versatility in interrupting a call in progress and in
  general enhances the user's feeling of "what's going on", especially
  if she/he is not all that well acquainted with the intricacies of
  system log files. Furthermore, it incorporates a mechanism to log ISP
  connections and calculate/store phone-call costs. It's also much nicer
  to look at as compared to connection scripts writing output on the
  terminal :) The main application, xisp, relies on a special dialer,
  xispdial, which is spawned by pppd in order to perform the dialing,
  and a "bare bones" terminal interface, xispterm. For more details on
  the workings of xisp, xispdial and xispterm, as well as their
  interaction with pppd and chat, see the "ARCHITECTURE" section below.
  The other facility provided by xisp is that of maintaining two small
  data bases, one for ISPs and one for phone companies (PTTs). The
  implementation supports a variable number of records for both data
  bases. Each ISP entry, aside from user account name and password,
  has space for 8 telephone numbers, two dialing parameters determining
  number of dialing tries and inter-dialing delay, sixteen user
  customizable script lines for the chat program, and a wealth of dialing
  and pppd options to cover most communication needs. All ISP data base
  information is saved in the xisp resource control file (.xisprc) in the
  user's home directory. The phone company database supports all (known)
  PTT attributes applicable while logging phone-call costs, and saves its
  information in a separate file, in sub directory .xisplogs, in the
  user's home directory. For details on the user interface look in the
  "USER INTERFACE" section below. As of version 1.9, the .xisprc file
  converter (xisprccv) provided with the distribution, understands all
  ISP data base formats beginning with version 1.2, and can be used to
  upgrade an old .xisprc file to the latest xisp version.


+--------------+
| ARCHITECTURE |
+--------------+

  The architecture of the xISP, xispdial and xispterm applications,
  and their interaction with pppd and chat is depicted in the
  schematic representation below.

                                 +-------------+
                                 |             |       +-------------+
   +-------------+               |             |       |             |
   |             |               |             | Exec \|  ip-up/     |
   |             |     Exec     \|    pppd     |-------|  -down and  |
   |             |---------------|             |      /|  children   |
   |             |              /|             |       |             |
   |             |               |             |       +-------------+
   |             |               +-------------+              | Output
   |             |                  /|\    | Exec             | 
   |    X-ISP    |                   |     |                  | 
   |    main     |           --------|-----|------------------
   |  interface  |          |        |     | 
   |             |          |   Stat |    \|/
   |             |   Named  |    +-------------+
   |             |/  Pipe  \|/   |             |       +-------------+
   |             |----------o----|             |/ Stat |             |
   |             |\        /|\   |             |-------|             |
   |             |          |   \|   xispdial  |\     \|  xispterm   |
   |             |---------------|             |-------|             |
   |             | Dialing  |   /|             | Exec /|             |
   +-------------+ Environ- |    |             |       +-------------+
          |        ment     |    +-------------+          /|\    |
          | Exec            |       /|\    | Script        |     |
          |                 |        |     |               |     |
          |                 |        |     |               | I/O |
          |                 |        |     |               |     |
         \|/                | Output |    \|/              |     |
   +-------------+          |    +-------------+           |    \|/
   |             |          |    |             |       +-------------+
   | ~/.xisp-up/ |  Output  |    |             |/      |             |
   |  -down and  |----------     |             |-------|             |
   |  children   |               |    chat     |\ I/O \|    MODEM    |
   |             |               |             |-------|             |
   +-------------+               |             |      /|             |
                                 |             |       +-------------+
                                 +-------------+


  The way it works goes like this. When an ISP is selected in xISP,
  a dialing environment file (.xispenv) is created in the user's
  home directory. The file contains all the information needed by
  xispdial in order to complete the dial, for example, the user account
  name, the password, the phone numbers to dial, and the script lines
  containing the special prompts used by the ISP during login. Then,
  pppd is started, with xispdial as its connect program. pppd then
  starts xispdial, which reads the dialing environment file, stores all
  the info internally and deletes the file. xispdial then proceeds to
  make the connection using chat. All output from chat as well as any
  report messages from xispdial are conveyed to xISP via a named pipe
  residing (by default) in /tmp (.xisppipe.<username>). After connection,
  and in the case that a manual login window is selected as desirable via
  xisp, xispdial starts xispterm, giving it control of the modem. The user
  can then login manually, and at the end to choose whether to complete
  successfully or to abort the connection. When a PPP interface is set
  up, and in the case that the ip-up/ip-down feature is used (read the
  pppd(8) manual page for detailed information on ip-up/ip-down), all
  output from ip-up and/or ip-down as well as from any processes spawned
  by them (read the ip-up and ip-down example scripts distributed with
  xisp) appears on the xisp browser window. Furthermore, as of version
  2.1, the supplied ip-up/ip-down scripts include DNS server selection
  capabilities on a per ISP basis, manipulating /etc/resolv.conf with
  DNS information passed on by xisp. In addition to ip-up/ip-down support,
  and as of version 2.3, xisp has the added capability of executing files
  .xisp-up or .xisp-down in the user's home directory, if they exist when
  the PPP link is setup or torn down respectively. Details on their use
  are included in the sample.xisp-up and sample.xisp-down files supplied
  with the xisp distribution. The link status, once a PPP link is
  set up, is monitored by xisp every 15 seconds. If for some reason the
  link drops, the status on your xisp window will be updated in at most
  15 seconds, at which time the "Connect" button will be activated again
  enabling you to redial for a new connection. If automatic redialing is
  selected, xisp will attempt to restore the connection by redialing the
  selected ISP. If PAP is selected for password authentication, xisp
  passes the username and password to pppd (ver. 2.2.0f) using the +ua
  option, via the .xisppap temporary file in the user's home directory.
  This file is generated just prior to launching pppd and is deleted after
  pppd forks to put itself in the background, hence remaining in the
  user's home directory for only a split second on a lightly loaded system.
  In the case that PAP-Secrets (PAP using the pap-secrets file) is selected,
  the username and remote-name specified within xisp are passed on to pppd
  via the 'user' and 'remotename' options, while if CHAP-Secrets (CHAP
  using the chap-secrets file) is selected, host and remote-host names are
  passed to pppd via the 'name' and 'remotename' pppd options. For both
  PAP-Secrets and CHAP-Secrets, appropriate entries must exist in files
  pap-secrets and chap-secrets respectively (read the pppd(8) manual
  page for syntax and details on their use). If pppd version 2.3.x is
  used with xisp, special option files called "xisp_<device>" (where
  <device> stands for your modem serial port(s)) must be installed in
  directory /etc/ppp/peers, while xisp starts pppd with the additional
  option "call xisp_<device>". The default peer information file generated
  when installing xisp is "xisp_modem" and corresponds to the "/dev/modem"
  special device.


+----------------+
| USER INTERFACE |
+----------------+

  When started, xisp displays a form with four buttons, three menus and
  a drop-choice list. Normally, in order to commence dialing, an ISP must
  be selected. The one selected by default right after startup is the
  first entry in the list of ISPs, or the one set as "Default ISP" from
  within the "Account Information" form. All defined ISPs appear in the
  drop list, for quick selection. The "Quit" button is always activated.
  The other button activated at this time is the "Connect" button. After
  a connection is initiated, and up until a PPP link is established,
  "Connect" is deactivated while "Interrupt" is activated. After a link
  is established, "Interrupt" is deactivated and "Disconnect" is
  activated. The "Help" menu selection is self explanatory, I guess :).
  The "Options" menu contains five items, "Account Information", "Dialing
  and Login", "Communication Options", "TCP/IP Options" and "Paths Setup".

  "Account Information"
     Brings up a list of ISP accounts to choose from, allowing editing
     of their properties. It also contains five input fields, one set
     of check buttons, one set of radio buttons, and four push buttons.
     The first time xisp is executed all ISP names will be blank. One can
     add an ISP entry by pressing the "Add" button. You can also create
     new entries by selecting existing entries, copying them by pressing
     the "Copy" button, and pasting them by pressing the "Paste" button.
     When adding or pasting entries, the new entry is always appended to
     the existing list of ISPs. Edit the ISP name by double-clicking on
     an entry in the list. The selected ISP can be set as the default
     selection upon xisp startup, by enabling the "Default ISP" check-
     button. If you want xisp to dial this ISP entry automatically after
     it starts up, enable the "Auto-dial upon startup" check-button. If
     you desire automatic re-dialing of dropped PPP connections to the
     selected ISP, enable the "Re-dial dropped links" check-button. Note
     that, contrary to the default ISP selection, auto-dialing and re-
     dialing of dropped links are per-ISP attributes. The first of five
     input fields contains the list of phone numbers to dial for the
     selected ISP, the second is the user account name to use, and the
     third is the password. The radio buttons enable use of password
     authentication via PAP, PAP using pap-secrets (PAP-Secrets) and CHAP
     using chap-secrets (CHAP-Secrets). Note that simple PAP (without
     using the pap-secrets file) is supported via the +ua pppd version
     2.2 option. Since this option has been removed from pppd in version
     2.3, this selection will be marked as unavailable when using xisp
     with pppd version 2.3 or later. The fourth input field contains the
     argument to the 'user' or 'name' argument to pppd, and the fifth
     contains the argument to the 'remotename' pppd argument. Note here
     that when any one of three available authentication methods is
     selected, any user script lines entered via the "Dialing and Login"
     menu, are ignored. In the phone number input field, more than one
     telephone numbers, and up to a total of 8 can be entered by
     separating them with the semicolon (';') character. The total length
     of each phone number is currently limited to 32 characters. A brief
     note on password security is in order here. The plaintext password
     entered in the "Password" input field is encoded using encrypt(3)
     with a key saved in the xisp executable. This key is itself
     scrambled so that it is not visible in the xisp binary. Since any
     one having access to the source can eventually come up with the key
     used, and potentially decode users' .xisprc entries yielding the
     plaintext ISP passwords, system administrators installing xisp are
     urged to change the key employed. For more details, read the
     SECURITY file included with the xisp distribution.

  "Dialing and Login"
     Brings up a window with fields for entering the three dialing
     parameters, namely the number of dialing tries, the inter-dialing
     delay and the maximum time to wait for modem connection, as well
     as up to eight user customizable script lines. It also enables the
     launching of a manual login window after a connection is established,
     the size of which can be specified via the "Terminal columns:" and
     "rows:" input fields, or enables ISP server call-back and editing of
     up to eight user customizable call-back script lines. All numeric
     input fields are pretty straight forward; the default values should
     be adequate for most cases. The sub-form for editing the call-back
     script is activated by pressing the "Options" button. This form also
     includes a field for entering the time to wait for the call-back
     connection.  The script section, both for dial-in and call-back, is
     divided into "Expect:" and "Send:" sections, as used by the call to
     the chat(8) command. Here the user must enter the script lines used
     by chat to successfully negotiate a login for the particular ISP.
     Dial-in and call-back lines are not used when manual login or
     authenticated (PAP/PAP-Secrets/CHAP-Secrets) login is selected.
     However, it is possible to use call-back with authenticated login.
     For detailed script-line syntax and various examples please read the
     chat(8) manual page. The following simple example should give you an
     idea. Let us assume that the ISP of interest employs a terminal server
     which prompts the user with 'Username:', then with 'password:' and
     then gives the server prompt, a single '>', at which point the user
     must type 'ppp' and press enter. The user customizable expect-send
     pairs for the above procedure would be:

        Expect:            Send:

        ername:--ername:   %U
        ssword:            %P
        >-->               ppp

     Note the special "%U" and "%P" variables in the script lines. "%U"
     is (quite obviously) replaced by your user account name (by the
     xisp program when it creates the dialing environment file), and "%P"
     by your password. A maximum of one "%U" and one "%P" can exist in
     either section (expect or send) of each script line. Entering more
     will make xisp print a message and abort the dial. All special
     escape characters supported by chat(8) (e.g. \n, \r etc.) can be
     entered in either the the "expect" or the "send" portion of a script
     line. In xisp versions prior to 2.5p3, any such special characters
     would have to be escaped by preceding them with an extra '\'. This
     is no longer needed as all characters beginning with '\' are now
     automatically escaped by xispdial. Note that since version 1.9 of
     xisp, when the script lines were divided into "Expect:" and "Send:"
     sections, you no longer need to enclose commands including spaces
     with single quotes. As an example, if at the end of the login session
     you start PPP using the command "ppp /compress", in versions prior
     to 1.9 you would need to enclose the command in single quotes and
     enter your script line as ">--> 'ppp /compress'" in the above
     example. For versions 1.9 and later this is not necessary, as
     expect-send pairs are automatically quoted before being passed on
     to chat.

  "Communication Options"
     Brings up a window with eight input fields and five sets of radio
     buttons. The "Device" input field is for selecting the special
     device file referring to the modem port, /dev/modem being the
     default. The input field named "Reset" contains the modem reset
     string, the field named "Init" enables customization of the modem
     initialization string (before dialing), and the "Connect String"
     field allows modification of the string by which the modem employed
     reports the connection speed. The default reset string is "ATZ"
     which should work with most modems. The default initialization
     string is a simple "AT" command, to which you could add, e.g. when
     using a USR modem, an "M0" to disable the speaker during modem
     operation. Note that xispdial appends an "H0" to the user defined
     initialization string. The string used for modem connection speed
     reporting is by default assumed to be "CONNECT". The sets of radio
     buttons enable selection of modem port (i.e. DCE<->DTE interface)
     speed, port flow control used (hardware or software), dialing mode
     (tone or pulse) and BSD software compression. The "Dialing extras"
     input field allows defining extra command characters (up to 8 in
     total) to be inserted between "AT" and "D" when dialing. The "Level"
     input field is the transmit and receive compression level as
     explained in the pppd(8) manual page, having a default value of 12.
     Note, however, that the PPP employed has to have BSD compression
     support for this option to have any effect; for Linux this happens
     only if you build PPP support as a kernel module. The last two input
     fields enable selection of the asyncmap and escape options provided
     by pppd; see the pppd(8) manual page for details on their function.
     The vast majority of dialup setups won't need the escape parameter,
     and that is the reason why it is off by default. The value of
     asyncmap, on the other hand, is automatically adjusted by your
     selection of flow control, i.e. whenever you change flow control
     type, the default value for asyncmap is inserted in the input field.
     Although the two default values should be adequate for general use,
     you can modify them further, to suit your needs.

  "TCP/IP Options"
     Brings up a window with seven input fields and four sets of radio
     buttons. With the exception of the primary and secondary DNS server
     entries, all remaining fields in this form are options which should
     only be changed if you understand their function; the default values
     are what you would need for your typical ISP connection. Please
     refer to the pppd(8) manual page for reading details on the function
     of these parameters, when you need to change their values. The last
     set of radio buttons enables DNS support via the ip-up and ip-down
     scripts, allowing  the user to enter IP addresses for a primary and
     (possibly) a secondary DNS server. The ip-up and ip-down scripts
     normally reside in /etc/ppp, and are automatically invoked by pppd
     when the link is set-up and torn-down respectively. Enabling this
     option will instruct xisp to do two things. Firstly, to call pppd
     with the extra option 'ipparam', passing a string as a sixth
     argument to ip-up and ip-down; this string contains the name of the
     pipe node from which xisp reads xispdial output, the description
     string entered via the "Account Information" form, and the primary
     (and possibly secondary) DNS server IP addresses entered via the
     corresponding input fields. Secondly, to read extra input from the
     named pipe node, after xispdial terminates, effectively writing any
     output from ip-up and ip-down to the xisp browser. The ip-up and
     ip-down scripts provided with xisp, must be installed in /etc/ppp
     for the xisp DNS settings to have any effect. Both ip-up and
     ip-down include user customizable sections for performing tasks
     like, for example, downloading mail or news, on a per ISP basis.

  "Paths Setup"
     Enables editing the paths to a) the pppd daemon, b) the location
     where pppd saves its process ID files, c) the chat utility, d) the
     xispdial and xispterm utilities and e) the location where xisp shall
     keep the named pipe node used for communicating with its components.
     All five paths are entered in corresponding input fields. For the
     first four, the "Default" button restores the path to its built-in
     default value specified during compilation. The "Status:" field
     beside each one of the first four entries will contain "OK" if the
     program binaries are indeed found in the specified path, or "Error"
     otherwise. IMPORTANT NOTE: the last path, i.e. the path to the
     named-pipe node, should NOT be on an NFS mounted filesystem.

  The "Logging" menu contains two items, "Logging Options" and
  "Statistics".

  "Logging Options"
     Brings up a window with  two sets of radio buttons, two drop
     choice lists, three buttons for phone company (PTT) manipulation,
     and an information display browser. The radio button set for the
     "OnLine Counter", enables selection of either "time in seconds"
     or "call charge" in local currency, as display option on the main
     program window. The other set of radio buttons enables selection of
     the logging period, affecting the file names of log files in the
     xisp logging directory $HOME/.xisplogs. Unless "None" is selected,
     two logging files are kept. One keeps track of the total time (in
     seconds) spent online as well as the total number of units charged
     (in the case when the chosen phone company charging method is "per
     minute" rather than "in units", this number is the total cost
     instead). The other log file keeps ISP connection logs for the
     desired logging period. The first file has the base name "xispcost"
     and suffixes of ".W<week number>", ".<abbr. month>" or
     ".B<month-pair number>", depending on whether "Weekly", "Monthly"
     or "Bimonthly" logging is selected. The second log file has base
     name "xisplog" and the same suffix as the first one. As an
     example, for date "Fri Sep 26 17:08:39 EET DST 1997", the suffixes
     would be ".W39", ".Sep" or ".B5" corresponding to "Weekly",
     "Monthly" or "Bimonthly" logging periods. Whenever the phone
     company and/or the logging period is changed, the old log file
     is renamed to <the old name>.bak, and a new one is created.
     The two drop choice lists are for selecting one of the supported
     phone companies and the charging zone from the zones defined for
     that company. The "Edit PTT" button brings up the PTT editor form
     for the selected PTT. This editor has its own help text, describing
     the usage of all supported PTT information fields, and explaining
     how user information is employed by the PTT tariff calculations.
     This help text is also included here, in section "PTT Editor" below.
     The "Add PTT" button creates a new phone company entry in file
     $HOME/.xisplogs/xispPTTs, prompting the user for the new PTT name,
     and then starting the PTT editor. The "Remove PTT" button removes
     the PTT entry currently selected. The information browser displays
     charging method and costs for all zones and time-of-day categories
     defined for the currently selected PTT. These categories are simply
     different charging tariffs used by the phone company for different
     times of day and night.

  "Statistics"
     Displays time/cost information collected in the xispcost.* files,
     according to the logging period selected. It displays the number of
     online seconds and total cost for each period on a text browser,
     and also makes a bar chart of costs for each corresponding period.
     The chart uses yellow color for the periods prior to the current
     one, white for the current period and dark cyan for the remaining
     periods up to the end of the current year. These remaining periods
     are assumed to belong to cost information collected during the
     previous year. For this reason, two different total time and cost
     values are calculated and displayed on the text browser, one for
     the periods up to and including the current one, and one for the
     remaining periods to the end of the year. Note that this menu
     option is active only if connection logs have been enabled from
     "Logging Options".
     
  "PTT Editor"
     This form enables editing the phone company information maintained
     by xisp. With the exception of the first three input fields (the
     PTT name, the number of charging zones defined for this PTT and
     the number of tariff categories per zone), all information is split
     up in three sections. Section "PTT charges" includes general
     information on PTT charging method and currency. Section "Zone
     information" enables editing the names and attributes of charging
     zones for the selected PTT. Last, "Category rules" enables editing
     the tariff categories (or otherwise termed "rules") for each zone.
     Tariff categories are comprised of a (complex attribute) rule and a
     cost value. If the rule applies, then the cost value is applied.
     The application of a rule depends on whether or not the attributes
     for this rule apply to the current calendar date and/or time. Note
     that the PTT tariff calculation engine in xisp searches zone
     categories in a first to last sequence, and applies THE FIRST
     matching rule ONLY. This should be kept in mind when writing and/or
     modifying category rules for a PTT entry. In the following
     paragraphs, the functionality of each field on the PTT editor form
     is described. Also note that in the text below, the "|" character
     is used as a short-hand for the word "or".

     General:
     --------

     PTT name:
       Enables changing the name string for the selected PTT.

     Charging zones:
       Used to specify the number of charging zones supported by the
       selected PTT entry.

     Categories/zone:
       Specifies the number of tariff categories (or rules) for each
       charging zone.
     

     PTT charges:
     ------------

     By unit:
       Specifies that the selected PTT charges its customers by a
       "unit" which costs a fixed amount of money. The rate (in seconds)
       at which such units are charged changes according to tariff rules.

     Minimum units:
       The minimum number of units charged for a call. This should not
       be confused with the "quantization" used by PTTs which charge
       "by unit". I.e. if the selected PTT charges a minimum of one unit
       per phone-call, don't put "1" in this input field, as this will
       result in 2 units being recorded by xisp for every short call
       you make. The PTT charges you with a single unit even if you don't
       consume the time corresponding to one unit during your short call.

     Per minute:
       Specifies that the selected PTT charges its customers by the
       minute. This also implies that the quantization in time
       measurement (and consequently charging) by the PTT is set to 60
       seconds. I.e. even even if your call lasts 23 seconds, you'll be
       charged for one minute.

     Minimum cost:
       This field is enabled both for "Per minute" and "Per second(s)"
       charging schemes. It specifies the minimum amount of money charged
       by the selected PTT for each phone-call. This minimum charge may
       correspond to a certain amount of time in a linear relationship
       fashion, or it may not (i.e. minimum charge-time is non linear --
       also see the "Zone Information" section).

     Per second(s):
       Specifies that the selected PTT charges its customers by a fixed
       number of seconds.

     Period:
       The charging period in number of seconds for "Per second(s)"
       charging schemes.

     Price/(unit|minute):
       The price in local currency for either each "unit", or for one
       minute if the charging scheme is "Per minute" or "Per second(s)".

     Currency:
       The local currency string for the selected PTT.

     Decimal digits for bill printouts:
       The number of decimal digits desired for saving/printing billing
       information in xisp's forms and log files.

     Currency placement:
       Specify "Left" or "Right" for the desired location of the
       currency string when printing out PTT charges.


     Zone information:
     -----------------

     Zone:
       Use this browser to select a zone for browsing/editing its
       information, by clicking on a line. Double-click to edit the zone
       name.

     Default tariff:
       Specifies the default tariff. For "By unit" charging schemes
       it is measured in seconds per unit. For "Per minute" and "Per
       second(s)" charging schemes, it is measured in the currency
       specified in the "Currency" field, per minute.

     Minimum charge time length:
       This field is defined only for "Per minute" and "Per second(s)"
       charging schemes. It specifies the fixed amount of time for which
       the "Minimum cost" applies. This can either be "Linear", in which
       case the "Minimum cost" lasts for time equal to the ratio of its
       cost value over 60, times its "Price/minute", or "Non-linear", in
       which case a fixed time length can be specified for each zone.

     Length for this zone (seconds):
       When the "Minimum charge time length" is non-linear, the "Minimum
       cost" shall last for the specified number of seconds, when the
       selected charging zone is in effect. As expected, this field is
       defined only for "Per minute" and "Per second(s)" charging
       schemes.
     
     Extra discount for this zone:
       Specifies whether or not there is any special discount for the
       selected zone. If "Yes", the discount specified in "Discount" as
       a percentage of the full charge, will be applied if the phone-
       call start time is not between the specified starting and ending
       period within the 24-hour day. This field is not defined for "By
       unit charging schemes".


     Category rules:
     ---------------

     Category number:
       Using this counter, select the category (or otherwise "rule")
       number which you wish to browse or edit.

     Category type:
       Specifies the type of the selected rule. "Weekday-special" and
       "Weekend-special" are used to specify reduced tariffs for dates
       during the calendar year, usually falling between two holiday
       dates, or within a holiday season. An example could be the
       weekend between Christmas and New Year's eve. "Holiday-absolute"
       is used for fixed holiday dates in the calendar year, like for
       example, national holidays. "Holiday-relative" is used for
       specifying holidays relative to (Catholic) Easter Sunday which
       is specified with index number "0". Good Friday is specified as
       "-2" while Pentecost as "50".

     Apply zone discount:
       Allows or disallows application of "Discount" (from "Zone
       information" above) to this rule. This facility is not defined
       for "By unit" charging schemes.

     Zero minimum charge time length:
       Allows inhibiting application of the minimum charge time length
       to this rule. This is for accommodating cases whereby "Minimum
       cost" is applied to each phone-call WITHOUT being linked to a
       specified charge time length, i.e. when the selected PTT charges
       "Minimum cost" as a base and adds to it the amount corresponding
       to the time the call lasts. This facility is not defined for "By
       unit" charging schemes.

     Rule tariff:
       Specifies the rule tariff. For "By unit" charging schemes it
       is measured in seconds per unit. For "Per minute" and "Per
       second(s)" charging schemes it is measured in the currency
       specified in the "Currency" field, per minute.

     Rule date:
       For "Holiday-absolute" specifies the calendar date only. For
       "Weekday-special" and "Weekend-special" you also need to specify
       the "End date", as the "Calendar date" is the starting date in
       this case. For "Holiday-relative", specify the relative date in
       the "Day relative to Easter Sunday" field.

     Rule start time and Rule end time:
       The starting and ending time during which the selected rule
       applies. Note that the time interval includes the "Rule start
       time" but not the "Rule end time", i.e. for specifying that a
       rule applies from 08:00:00 to 10:59:59 inclusive, start time
       would be entered as 08:00:00 and ending time as 11:00:00. This
       follows standard PTT conventions with regards to changes in
       tariff as a function of time within the 24-hour day.


  The main window includes one status and three connection indicators.
  the status indicator appears below the program icon, indicating the
  current interface state. There are three distinct states: "OFF-LINE"
  for "disconnected", "XISPDIAL" indicating that dialing is in progress
  and "ON-LINE". The "Assigned IP Address:" indicator prints the IP
  address assigned to your PPP interface after successfully establishing
  a link. The "Modem Speed:" indicator prints the speed as returned by
  the modem connection-speed string, and the "Time On-Line"/"Call Charges"
  indicator measures your connection time or charges with a resolution
  of five seconds. The measured time (or sum of charges) will remain
  there after disconnection, until a new dialing sequence is initiated.
  The IP address can be selected for later pasting in some other window
  by clicking the left mouse button on the IP readout. Clicking again
  deselects it.


+---------+
| SIGNALS |
+---------+

  The following signals have the specified effect when sent to the xisp
  process using the kill(1) command:

   SIGINT,SIGTERM: The xisp process is terminated and the PPP link is
                   disconnected.

   SIGUSR1:        If xisp is in the disconnected state, sending it this
                   signal is equivalent to pressing the "Connect" button.
                   If xisp is either dialing or in the connected state,
                   this signal has no effect.

   SIGUSR2:        If xisp is dialing, sending it this signal is
                   equivalent to pressing the "Interrupt" button, and if
                   xisp is in the connected state, it is equivalent to
                   pressing "Disconnect". If xisp is in the disconnected
                   state, this signal has no effect.

  Look in contrib/README and contrib/.fvwm2rc.add for an example on how
  this feature could be used to control xisp from a window-manager menu.


+----------+
| XISPDIAL |
+----------+

  The script employed by xispdial for the connection is the
  concatenation of its internal script, and the user customizable script
  lines entered via xisp. The internal script used is the following:

     TIMEOUT        3
     ABORT          BUSY
     ABORT          'NO CARRIER'
     ABORT          'NO DIALTONE'
     ABORT          enied
     ABORT          imeout
     ''             'AT <dial extras>D<dialing method> <the phone number>'
     TIMEOUT        <maximum wait for connection>
     <connect str>  \c 
     TIMEOUT        5
     \r             \c

  The "connect str" is the string returned by your modem ypon connection
  (it's "CONNECT" for a US Robotics Sportster, but it might be the word
  "CARRIER" for your modem; please consult with your modem's user manual).
  As seen above, the timeout value after connection is set to 5 seconds.
  If for some reason it takes more than that to log into a system, one
  could specify a new timeout value in the user script lines. For
  instance, in the example given in the previous section, if it takes 6
  seconds for a prompt from the terminal server in question, the user
  customizable expect-send pairs could be:

     Expect:            Send:

     ername:--ername:   %U
     ssword:            %P
     TIMEOUT            10
     >-->               ppp

  allowing 10 (6 + an extra 4) seconds for receiving the '>' character.
  If call-back is selected, the following script is appended to the
  concatenation of user customizable script lines and a modified version
  of the internal script:

     TIMEOUT        <delay for call-back connection>
     <connect str>  \c
     TIMEOUT        5
     \r             \c

  And following that, the user call-back script lines are appended to it.
  This instructs chat to wait the user-specified delay time for a second
  connect from the server as it dials back, and then to use the login
  procedure described in the call-back script. The dial-in internal
  script is modified by deleting the

     ABORT    'NO CARRIER'

  expect-send pair, since the carrier drops when the remote side hangs-up
  prior to calling back.


+----------+
| XISPTERM |
+----------+

   xispterm is a stripped-down version of a terminal emulation program
  which is used by xispdial as a manual login window. It only understands
  the backspace (^H) and kill (^U) control characters, but it gets the
  job done! Also note that it can also be used independently as a quick
  pppd dialer as follows. Stick all your pppd options in a file, and then
  invoke pppd with xispterm as dialer and your file as the options file.
  If, for example, you saved the options in a file called "myopts", and
  xispterm resides in the directory /usr/lib/ppp/xispterm, the command
  line to invoke pppd would be:

             pppd file myopts connect /usr/lib/ppp/xispterm

  Then, you could talk directly to your modem, dial a number with an AT
  command, once connected you would login to your ISP and start PPP on
  the remote end, and then you would press the "Continue" button to tell
  pppd that all is OK for setting up the link. Pressing "Abort" would
  terminate pppd and your connection along with it.


+----------+
| XISPRCCV |
+----------+

   xisprccv is a .xisprc file converter for version 1.2 and up to the
  current version, and it is run without arguments. Before performing the
  upgrade, it creates a backup copy of the user's .xisprc file in her/his
  home directory, with a '-V.R' suffix, where 'V' is the version and 'R'
  the revision number.


+----------------+
| TESTED SYSTEMS |
+----------------+

  I have built and tested the xisp package under Linux-ix86 kernel
  versions 2.0.28 - 2.0.35, ppp-2.2.0f, libforms.so.0.88 with X11R6
  libX11.so.6.0 as well as X11R6.1/X11R6.3 libX11.so.6.1. The modem
  used was a 28.8 US Robotics Sportster. Versions 2.2 and later were
  also tested under SunOS-4.1.4, ppp-2.2, libforms.so.0.88 with
  X11R6 libX11.so.4.20 and X11R6.1/X11R6.3 libX11.so.4.30. Versions
  2.5 and later were additionaly tested under Solaris-2.5, ppp-2.3.5,
  libforms.so.0.88 with X11R6 libX11.so.4.20, using two US Robotics
  Sportster modems, a 14,400 and a 33,600 Baud model.


+--------+
| AUTHOR |
+--------+

  The author of xisp can be reached at:
 +---------------------+-------------------------------------------+
 | Dimitrios P. Bouras |          Tel.: +30 1 968-0554 or 894-1320 |
 | 41 Pandora Str.     | E-mail: dbouras@hol.gr, d.bouras@ieee.org |
 | 166 74 Athens       |         dimitri@ee.ubc.ca                 |
 | GREECE              |         Web: http://users.hol.gr/~dbouras |
 +---------------------+-------------------------------------------+