Table of Contents
*****************

Chestnut Dialer
1 General Information
  1.1 About
  1.2 Features
  1.3 Requirements
    1.3.1 Basic Requirements
    1.3.2 GTK2 Interface Requirements
    1.3.3 QT Interface Requirements
    1.3.4 File Access Requirements
2 Installation
  2.1 Compiling ppp with CBCP Support
  2.2 Installation from Sources
  2.3 Installation from RPM packages
3 Usage
  3.1 First Run
  3.2 Command Line Interface
  3.3 Chat Scripts
    3.3.1 Predefined Scripts
    3.3.2 Custom Script
  3.4 Custom Window Title
  3.5 Using Call-back
  3.6 Configuring Dialin Server
    3.6.1 Authentication
    3.6.2 Client Configuration
  3.7 Null Modem Link
  3.8 Account Attributes
  3.9 Connection Parameters
4 Acknowledgements
Appendix A Copying This Manual
  A.1 GNU Free Documentation License
    A.1.1 ADDENDUM: How to use this License for your documents


Chestnut Dialer
***************

This is a manual for Chestnut Dialer (version 0.3.3), a PPP dialing
program.  This manual is not finished; some parts will be added in
future.

   Copyright (C) 2004, 2005 Konstantin Korikov

   English translation by Gleb Kavalenka, Konstantin Korikov

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.2 or any later version published by the Free Software
     Foundation; with no Invariant Sections, no Front-Cover Texts, and
     no Back-Cover Texts.  A copy of the license is included in the
     section entitled "GNU Free Documentation License".

1 General Information
*********************

This chapter provides general information on Chestnut Dialer.

1.1 About
=========

Chestnut Dialer is PPP (Point to Point Protocol) dialing program,
written in Python.  Many Internet providers, that provide dialup
service, use PPP protocol; this program helps you to connect to
Internet using a modem. Current version (0.3.3) can work with GTK2, QT,
or without GUI (command line interface).  You can run Chestnut Dialer
with user's priviliges (it doesn't require root permissions), but it
requires read and/or write access to some system files (including the
modem device). Chestnut Dialer uses standard pppd daemon to set up
network interface.

   Copyright (C) 2003, 2004, 2005 Konstantin Korikov <lostclus@ua.fm>

   Project home page is `http://chestnut-dialer.sourceforge.net/'

   Please send bugs, questions and proposals to the author.

   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; either version 2 of the License, or (at
your option) any later version.

1.2 Features
============

   * Account manipulation, including import from other programs

   * Default account

   * Command line interface

   * Call-back configuration

   * Auto redialling

   * Setting up minimum connection speed

   * Dialin server configuration

   * Null Modem Link

1.3 Requirements
================

1.3.1 Basic Requirements
------------------------

Minimum software required for Chestnut Dialer to work:

   * Linux (may work in other OS, not tested), `http://linux.org/'

   * Python must be installed, `http://www.python.org/'

   * ppp package must be installed (`pppd', `chat'),
     `ftp://ftp.samba.org/pub/ppp/'. For using call-back ppp must by
     compiled with CBCP (Call Back Configuration Protocol) support

   * Python binding for libxml2 (libxml2-python), `http://xmlsoft.org/'

1.3.2 GTK2 Interface Requirements
---------------------------------

Libraries needed for using GTK2 user interface:

   * Python binding for GTK2 (pygtk2), `http://pygtk.org/'

   * Python binding for libglade (pygtk2-libglade, included in pygtk2)

1.3.3 QT Interface Requirements
-------------------------------

Libraries needed for using QT user interface:

   * Python binding for QT (PyQt),
     `http://www.riverbankcomputing.co.uk/pyqt/'

1.3.4 File Access Requirements
------------------------------

   * `pppd' must have suid attribute and belong to root

   * `/etc/resolv.conf' must be accessible for read and write

   * `/etc/ppp/resolv.conf' must be accessible for read

   * Modem device must be accessible for read and write

   * `chat' must be accessible for execute

   * `ifconfig' must be accessible for execute

2 Installation
**************

This chapter describes the installation procedure.

2.1 Compiling ppp with CBCP Support
===================================

If you want to use call-back then you need to make sure that daemon
pppd (package ppp) supports it.  To check if pppd supports callback,
type in the shell:

     /usr/sbin/pppd dryrun callback 123

   If pppd is installed in other directory, then specify the correct
path.  If you see message:

     /usr/sbin/pppd: unrecognized option 'callback'

   it means that pppd was compilled without CBCP support.

   To enable CBCP support in OS Linux do the following:

  1. Untar the ppp source code package (you can download it from
     `ftp://ftp.samba.org/pub/ppp/')

  2. In file `pppd/Makefile.linux' find string `#CBCP=y' and replace it
     with `CBCP=y'

  3. Configure `./configure', compile `make', and install `make
     install' everything

   Refer to ppp package documentation for more details.

2.2 Installation from Sources
=============================

It is recommended that you remove the previously installed version
before installing a new version so that no unnecessary files are left
on the disk. User data may stay, and they will be automatically
converted into the new version, if needed.

  1. Untar the archive:

          bzip2 -cd chestnut-dialer-0.3.3.tar.bz2 | tar xvf -

  2. Go to the top-level directory:

          cd chestnut-dialer-0.3.3

  3. Configure the package:

          ./configure

     Note: Script configure can receive command line arguments.  You
     can specify destination directory, disable unnecessary user
     interfaces, etc., using these arguments. You can get the complete
     list of options by typing `./configure --help'.

  4. Build and install everything:

          make
          make install

     Note: You may need to run `make install' as root.

2.3 Installation from RPM packages
==================================

Chestnut Dialer divided into a number of RPM packages:
`chestnut-dialer-0.3.3-1.noarch.rpm'
     main package

`chestnut-dialer-gtk2-0.3.3-1.noarch.rpm'
     contains GTK2 user interface

`chestnut-dialer-qt-0.3.3-1.noarch.rpm'
     contains QT user interface
   To install all packages, type:

     rpm -i chestnut-dialer-0.3.3-1.noarch.rpm \
     chestnut-dialer-gtk2-0.3.3-1.noarch.rpm \
     chestnut-dialer-qt-0.3.3-1.noarch.rpm

   To upgrade all packages, type:

     rpm -U chestnut-dialer-0.3.3-1.noarch.rpm \
     chestnut-dialer-gtk2-0.3.3-1.noarch.rpm \
     chestnut-dialer-qt-0.3.3-1.noarch.rpm

   If you don't want to install some interfaces, just don't install
their respective packages.

3 Usage
*******

This chapter describes basic concepts of using Chestnut Dialer.

3.1 First Run
=============

To run Chestnut Dialer, type in the shell:

     chestnut-dialer -i interface_name

   where interface_name is either `gtk2' or `qt'.  Then the main window
of the program main will appear.

   Note: To avoid specifying interface in the command line every time,
edit `~/.chestnut-dialer/preferred-ui-X', where ~ stands for the user
home directory, X is X11 or console.

   To create a new account, click the AccountsConf button, then click
the New button. The account editing window will appear.  Enter the
account name (field Account Name), for example `Provider CoolOnline',
in the Dial tab. Then fill out the list of modem pool telephone numbers
in the Phone Numbers tab. To do this, enter a number in field "#" and
click the Add button. Repeat this operation for each number if you have
more than one number.  Then enter the user name and password in the
Authentication tab.  Then click the OK button.

   To connect to the provider, select an account from list (click on
it) and click the Dial button which is located below.  The program will
switch to the Connecting mode. After the connection has been
established successfully, the main window will show a table with
connection parameters. Start your preferred browser and enjoy Internet.

   To disconnect, click button Disconnect.

3.2 Command Line Interface
==========================

Synopsis
--------

     chestnut-dialer [basic options] [command [options]
                     [attribute_name=value | unset attribute_name]...]

Description
-----------

If no arguments are supplied, then Chestnut Dialer runs with the user
interface specified in file `~/.chestnut-dialer/preferred-ui-X', where
~ stands for the user home directory, X is X11 or console.  If there is
no such file, then the program attempts to determine the preferred user
interface based on the current environment (X11 or console).

   All commands except `--dial' either disable the user interface or
use interface `none'.  The program terminates as soon as the command
has been executed.

   Command `--dial' is an exception: the program will remain running as
long as a connection exists if interface `none' is used; the program
will remain running until the user stops it if another interface is
used.  To disconnect the connection established while using interface
`none', press <Ctrl+C> on the keyboard.

Exit Status
-----------

0
     Successful termination. Chestnut Dialer terminated at the user's
     request.

1
     Command line usage error.

2
     Invalid arguments are supplied (e.g. invalid account identifier,
     invalid user interface).

3
     Unknown error.

4
     No dialtone.

5
     Line is busy.

6
     No carrier detected.

7
     Authentication failure.

8
     Internal software error.

9
     Operating system error.

Basic Options
-------------

`-i interface_name'
`--ui=interface_name'
     Specifies the user interface.  Use command `--list-ui' to get a
     list of all possible interfaces.

`--ui-param=name:value'
     Passes a parameter to the user interface.  Multiple `--ui-param'
     options may be specified.  Use command `--list-ui-params' to get
     list of all possible parameters.

`--debug=integer'
     Sets the debugging information output level.  The program sends
     debugging info to the standard error stream.  Level 0 means output
     of fatal errors only.  The more the value, the more info is sent
     to the output.  The default value is 2.

`--no-headers'
     Disables printing of the header line in all lists.

`--daemon'
     Detach from controlling terminal.

Commands
--------

`-d'
`--dial'
     Dial.

`-s'
`--disconnect'
     Disconnect.

`-e'
`--erase'
     Delete the account.

`-c'
`--create'
     Create a new account and print its identifier.

`-m'
`--modify'
     Modify the existing account.

`-p'
`--print'
     Print the account.

`--print-full'
     Print the account with all default values.

`-l'
`--list-accounts'
     List accounts.  Prints a table, the first column contains
     identifiers, the second column contains account names.

`--list-ui'
     List installed user interfaces.  Prints a table, the first column
     shows interface names, the second column shows interface types,
     the third column shows the author, the 4-th column shows the
     description.

`--list-ui-params'
     List parameters that the currently selected user interface can
     process.  Prints a table, the first column contains parameter
     names, the second column shows the parameter type, the third
     column shows the description.

`--list-acc-attrs'
     List all possible account attributes.  Prints a table, the first
     column contains attribute names, the second column shows the
     attribute type.

`-q'
`--quit'
     Disconnect and terminate existing process (if there is no such
     process, Chestnut Dialer notifies you).

`-?'
`--help'
     Print short usage info.

`--version'
     Print the program name and version.

Command Options
---------------

`-a integer'
`--account=integer'
     Selects the account by the ID number.

`-n name'
`--account-name=name'
     Selects the account by the name. First account whose name contains
     a value of given argument will be selected. Search is not case
     sensitive.

Account Attributes
------------------

See a description of all account attributes in *Note Account
Attributes::.

   Keyword `unset' resets an attribute to its default value.

   Values of boolean attributes can be specified as: `on' or `off', or
`yes' or `no', or `1' or `0'.  The value for a `list' attribute may be
specified as a list of values separated by commas.

Examples
--------

Create an account:

     chestnut-dialer -c name="CoolOnline" phone_numbers=555,666 \
     user=larry passwd=secret

   Dial using account CoolOnline (CoolOnline is the account name).

     chestnut-dialer -i none -dn CoolOnline

   Dial using a modified account with account identifier 1 (the program
does not save new attribute values, it uses the new attibute values for
one connection only):

     chestnut-dialer -i none -da 1 phone_numbers=777 redial_attempts=5

   Modify account CoolOnline:

     chestnut-dialer -mn CoolOnline phone_numbers=777 redial_attempts=5

   Print account 1 (1 is the account identifier):

     chestnut-dialer -pa 1

   Delete account 1 (1 is the account identifier):

     chestnut-dialer -ea 1

3.3 Chat Scripts
================

Often there is something which needs to be done to prepare the link
before the PPP protocol can be started; chat script is used for this
purpose. Usually chat script is required to initialize the modem and
dial the appropriate phone number, but sometimes it also required for
authentication purpose.

3.3.1 Predefined Scripts
------------------------

The program have few predefined chat scripts:

   * "Predefined - No Terminal Authentication" (`predef-noterm')

   * "Predefined - Terminal Authentication" (`predef-term')

   * "Predefined - Any Authentication" (`predef-auto')

   * "Predefined - Dialin" (`predef-dialin')

   `predef-noterm' is simple script, that don't uses terminal
authentication.  It is suitable only for PAP (Password Authentication
Protocol) and CHAP (Challenge Handshake Authentication Protocol)
authentication.

   `predef-term' is simple script, that uses terminal authentication.
It is suitable only for terminal authentication.

   `predef-auto' is more complex, and can automatically determine
authentication type.  It is suitable for PAP, CHAP, and terminal
authentication.

   `predef-dialin' is used to wait for and answer to incomming calls.

   You can select predefined script in field Use Script which is in tab
Authentication in the account editing window. Or, if you use command
line interface, by assigning appropriate value to the `use_script'
account attribute.

3.3.2 Custom Script
-------------------

You can specify your own chat script for connecting.  Go to tab
Authentication in the account editing window, then in Use Script field
select Custom, then write your script in tab Custom Script.  The syntax
of the chat script is the same as the syntax of program chat, see
chat(8) man page.  Chat scripts can use predefined macros. The syntax
for calling a macro is: `%(macro_name)s'.  There are predefined macros
that contain account attributes.  Names of these macros are same as
names of the account attributes they contain, see *Note Account
Attributes::.  Additionally, you can use following macros:

Macro Name               Description
phone_number             Current ISP phone number.
vol_cmd                  Modem command that sets speaker volume.

   Example of a simple chat script with macros:

     ABORT 'BUSY'
     ABORT 'ERROR'
     ABORT 'NO CARRIER'
     ABORT 'NO DIALTONE'
     ABORT 'Invalid Login'
     ABORT 'Login incorrect'
     '' ATZ
     OK 'ATDT%(phone_number)s'
     CONNECT ''
     'ogin:' '%(user)s'
     'ord:' '%(passwd)s'
     TIMEOUT 5
     '~--' ''

3.4 Custom Window Title
=======================

You can customize the window title for three program modes:
"Disconnected", "Connecting" and "Connected" in dialog Options.  You
can use predefined macros in the format string. Syntax for calling a
macro is: `%(macro_name)s'. The set of available macros depends on the
program mode. You can use macros `program_name' and `program_version',
indicating the program name and version, in all modes. You can use
account attributes as macro names in "Connecting" and "Connected"
modes, see *Note Account Attributes::. You can use connection parameters
as macro names in "Connected" mode, see *Note Connection Parameters::.

   Example of format string for "Disconnected" mode:

     Disconnected

   Example of format string for "Connecting" mode:

     Connecting to %(name)s

   Example of format string for "Connected" mode:

     Connected to %(name)s at rate %(speed)s

3.5 Using Call-back
===================

To enable call-back, go to the account editing window, then go to the
PPP tab, check the "Provider will call-back (CBCP)" checkbox and enter
your phone number in the "Call-back Phone Number" field.  If you use
command line interface, then use *Note account attributes: Account
Attributes.  `callback' and `callback_phone_number'.

   If the program fails to establish a connection and you see message

     /usr/sbin/pppd: unrecognized option 'callback'

   then recompile the ppp package with CBCP support, see *Note
Compiling ppp with CBCP Support::.

3.6 Configuring Dialin Server
=============================

Chestnut Dialer can be used as dialin server, it can handle incoming
calls to establish a PPP connection with remote machine (client). This
can be done by making special account and "dialing" using it. When you
dial using dialin account Chestnut Dialer begins to wait for incoming
call, and when it occurs do answer and establishes PPP connection.

   To make dialin account, create new account and setup following
values:

     Redial Forever: on
     Redial Auto: on
     Authentication Type: Terminal
     Use Script: Predefined - Dialin
     Ask Password: off
     Local IP Address: 192.168.5.1
     Netmask: 255.255.255.0
     Remote IP Address: 192.168.5.2
     Add Default Route: off

   Note: if you connected to LAN (Local Area Network), make sure that
you don't use same network numbers (see ifconfig(8)).

   Also you can create this account using command line interface:

     chestnut-dialer -c name=dialin redial_attempts=0 redial_auto=on \
     auth_type=term use_script=predef-dialin ask_passwd=off \
     ip=192.168.5.1 mask=255.255.255.0 remote=192.168.5.2 \
     default_route=off

3.6.1 Authentication
--------------------

Account that provided bellow don't use any authentication, this means
that client may use any user name and password. But if you need
authentication, add to PPP Options following options `auth
require-pap', and add to `/etc/ppp/pap-secrets' file following line:

     "username" hostname "userpassword" *

   where `username' stands for user name, `hostname' stands for your
host name (you can get it using hostname(1)), `userpassword' stands for
password. You can add multiple lines with different user names and
passwords. See details in pppd(8).

3.6.2 Client Configuration
--------------------------

Clients must dial to your phone number and use PPP protocol. User name
and password depends on your configuration.  If you don't configure any
authentication, then clients may use any user name and password,
otherwise each client must use one of pairs user name/password, that
you added to `/etc/ppp/pap-secrets' file, in this case client must use
PAP authentication.

   In order to access your services, remote client must use 192.168.5.1
address (or that you type as local IP address).  For example:

     ftp://192.168.5.1
     http://192.168.5.1

3.7 Null Modem Link
===================

You can use Chestnut Dialer to connect two computers via null modem
cable. On the first computer create following account:

     Redial Forever: on
     Redial Auto: on
     Authentication Type: Terminal
     Use Script: None
     Ask Password: off
     Local IP Address: 192.168.5.1
     Netmask: 255.255.255.0
     Remote IP Address: 192.168.5.2
     Dial Device: /dev/ttyS0
     Use the Modem Control Lines: off
     Add Default Route: off
     PPP Options: passive

   On the second:

     Redial Forever: on
     Redial Auto: on
     Authentication Type: Terminal
     Use Script: None
     Ask Password: off
     Local IP Address: 192.168.5.2
     Netmask: 255.255.255.0
     Remote IP Address: 192.168.5.1
     Dial Device: /dev/ttyS0
     Use the Modem Control Lines: off
     Add Default Route: off
     PPP Options: passive

   Note: if you connected to LAN, make sure that you don't use same
network numbers (see ifconfig(8)).

   The dial device must match the serial port that you use (where cable
is connected). For Linux:

     COM1 - /dev/ttyS0
     COM2 - /dev/ttyS1
     COM3 - /dev/ttyS2
     COM4 - /dev/ttyS3

3.8 Account Attributes
======================

Attribute Name           Type      Description
answer_cmd               string    Modem command for ansering an
                                   incoming call (`ATA').
ask_passwd               boolean   Ask user for password when
                                   connecting.
auth_type                string    Authentication type. Valid values:
                                   `pap/chap', `term'.
busy_resp                string    Modem response 'busy'.
callback                 boolean   Use call-back.
callback_init2_cmd       string    Second modem init string when
                                   waiting for an incoming call.
callback_init_cmd        string    Modem init string when waiting for
                                   an incoming call.
callback_phone_number    string    Phone number for the provider to
                                   call back.
chat_login_prompt        string    Login prompt.
chat_passwd_prompt       string    Password prompt.
chat_script              text      Chat script, see *Note Chat
                                   Scripts::, chat(8) man page.
comment                  text      Account comment.
connect_program          string    Command to execute after connecting
                                   (it is passed to the shell).
connect_resp             string    Modem response 'connection'.
default_route            boolean   Add default route.
device                   string    Dial device file that used to
                                   communicate with the peer.  Usually
                                   this is the serial port which modem
                                   connected to.
dial_cmd                 string    Modem command that is used for
                                   dialling.  Use `ATDT' for
                                   touch-tone dialing, or use `ATDP'
                                   for pulse dialing.
dial_prefix              string    Dial prefix.
dial_timeout             integer   Maximum waiting time for modem
                                   connection, seconds.
disconnect_program       string    Command to execute after
                                   disconnecting (it is passed to the
                                   shell).
dns_servers              list      DNS server list.  The empty list
                                   means that the provider specifies
                                   the addresses.
error_resp               string    Modem response 'error'.
flow_control             string    Flow control.  Valid values are:
                                   `crtscts', `cdtrcts', `xonxoff',
                                   `no-change'.  `crtscts' - hardware
                                   flow control using the RTS and CTS
                                   signals in the RS-232 interface.
                                   `cdtrcts' - non-standard hardware
                                   flow control using the DTR and CTS
                                   signals.  `xonxoff' - software flow
                                   control.  The `no-change' value
                                   means that flow control setting for
                                   the serial port is left unchanged.
hangup_cmd               string    Modem command 'hang up'.
hangup_resp              string    Modem response 'hang up'.
id                       integer   Account identifier is a unique
                                   integer number.  The program
                                   automatically assigns a value to
                                   this attribute and the user can't
                                   modify it.
init2_cmd                string    Second modem initialization string.
init_cmd                 string    Modem initialization string.
init_resp                string    Modem response to the init string.
ip                       string    Local IP address.  The empty value
                                   means that the provider specifies
                                   the address.
lock_device              boolean   Lock the modem device.
low_vol_cmd              string    Modem command that sets speaker
                                   volume to 'low'.
mask                     string    Net mask.  The empty value means
                                   that the provider specifies the
                                   mask.
max_vol_cmd              string    Modem command that sets speaker
                                   volume to the maximum.
min_speed                integer   Minimum connection baud rate.
modem                    boolean   Use the modem control lines.
modem_term               string    Modem string end sequence.  Valid
                                   values is `\r\n', `\r', `\n'.
modem_timeout            integer   Maximum waiting time for modem
                                   response, in seconds.
mru                      integer   Maximum reception unit, in bytes.
mtu                      integer   Maximum transmission unit, in bytes.
mute_cmd                 string    Modem command that disables the
                                   speaker.
name                     string    Account name.
noanswer_resp            string    Modem response 'no answer'.
nocarrier_resp           string    Modem response 'no carrier'.
nodialtone_resp          string    Modem response 'no dial tone'.
passwd                   string    Password.
phone_numbers            list      List of phone numbers to dial.
ppp_options              string    Additional options passed to pppd,
                                   see pppd(8) man page.
ppp_timeout              integer   Maximum PPP waiting time, in
                                   seconds.
prompt_timeout           integer   Maximum prompt waiting time, in
                                   seconds.
redial_attempts          integer   Number of redial attempts before
                                   notifying the user about failure to
                                   establish a connection. Zero value
                                   means redial forever.
redial_auto              boolean   Auto redial when the connection has
                                   been lost.
redial_if                list      This attribute controls whether or
                                   not repeat dial attempt depends on
                                   result of previous attempt. List
                                   can contain following values:
                                   `no-dialtone', `auth-fail'.
                                   `no-dialtone' allows redialing if
                                   previous attempt result is no dial
                                   tone.  `auth-fail' allows redialing
                                   if previous attempt result is
                                   authentication fail.
remote                   string    Remote IP address.  The empty value
                                   means that the provider will
                                   specify the address.
remotename               string    The assumed name of the remote
                                   system for authentication purposes.
                                   When authentication type is
                                   `pap/chap' and no passwordfd plugin
                                   is used, pppd looks for password in
                                   file `pap-secrets' or
                                   `chap-secrets' using this name.
                                   See details on pppd(8) man page.
ring_resp                string    Modem response 'ring'.
speed                    string    Modem baud rate.
user                     string    User name (login).
use_passwordfd           boolean   Use pppd passwordfd plugin to pass
                                   password to the daemon.
use_script               string    This attribute determines what chat
                                   script to use.  Valid values are:
                                   `predef-noterm', `predef-term',
                                   `predef-auto', `dialin', `custom',
                                   `none'.
vol_resp                 string    Modem response to the volume
                                   setting command.
volume_setting           integer   Volume setting. Valid values are 0
                                   to 2.

   Note: to insert new line and carriage return characters in modem
init and response strings use backslash escape sequences `\n' and `\r'
respectively. To insert backslash use `\\'.

3.9 Connection Parameters
=========================

Parameter Name           Description
account_name             Account name.
interface                Network interface.
local_ip                 Local IP address.
netmask                  Net mask.
remote_ip                Remote IP address.
rx                       Number of received packets.
rx_bytes                 Number of received bytes.
speed                    Connection baud rate.
time                     Connection time. Format `hh:mm:ss'.
tx                       Number of transmitted packets.
tx_bytes                 Number of transmitted bytes.

4 Acknowledgements
******************

   * We wish to thank the people whose work is used in this project. A
     short list of projects: `http://www.python.org',
     `http://xmlsoft.org', `http://www.gtk.org', `http://www.pygtk.org',
     `http://www.troll.no', `http://www.riverbankcomputing.co.uk/pyqt/'.

   * Gleb Kavalenka, who helped with English translation of manual.

   * Matvey, who helped with detecting bugs.

   * The persons who reported bugs and proposed new features.

Appendix A Copying This Manual
******************************

A.1 GNU Free Documentation License
==================================

                      Version 1.2, November 2002

     Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
     59 Temple Place, Suite 330, Boston, MA  02111-1307, USA

     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

  0. PREAMBLE

     The purpose of this License is to make a manual, textbook, or other
     functional and useful document "free" in the sense of freedom: to
     assure everyone the effective freedom to copy and redistribute it,
     with or without modifying it, either commercially or
     noncommercially.  Secondarily, this License preserves for the
     author and publisher a way to get credit for their work, while not
     being considered responsible for modifications made by others.

     This License is a kind of "copyleft", which means that derivative
     works of the document must themselves be free in the same sense.
     It complements the GNU General Public License, which is a copyleft
     license designed for free software.

     We have designed this License in order to use it for manuals for
     free software, because free software needs free documentation: a
     free program should come with manuals providing the same freedoms
     that the software does.  But this License is not limited to
     software manuals; it can be used for any textual work, regardless
     of subject matter or whether it is published as a printed book.
     We recommend this License principally for works whose purpose is
     instruction or reference.

  1. APPLICABILITY AND DEFINITIONS

     This License applies to any manual or other work, in any medium,
     that contains a notice placed by the copyright holder saying it
     can be distributed under the terms of this License.  Such a notice
     grants a world-wide, royalty-free license, unlimited in duration,
     to use that work under the conditions stated herein.  The
     "Document", below, refers to any such manual or work.  Any member
     of the public is a licensee, and is addressed as "you".  You
     accept the license if you copy, modify or distribute the work in a
     way requiring permission under copyright law.

     A "Modified Version" of the Document means any work containing the
     Document or a portion of it, either copied verbatim, or with
     modifications and/or translated into another language.

     A "Secondary Section" is a named appendix or a front-matter section
     of the Document that deals exclusively with the relationship of the
     publishers or authors of the Document to the Document's overall
     subject (or to related matters) and contains nothing that could
     fall directly within that overall subject.  (Thus, if the Document
     is in part a textbook of mathematics, a Secondary Section may not
     explain any mathematics.)  The relationship could be a matter of
     historical connection with the subject or with related matters, or
     of legal, commercial, philosophical, ethical or political position
     regarding them.

     The "Invariant Sections" are certain Secondary Sections whose
     titles are designated, as being those of Invariant Sections, in
     the notice that says that the Document is released under this
     License.  If a section does not fit the above definition of
     Secondary then it is not allowed to be designated as Invariant.
     The Document may contain zero Invariant Sections.  If the Document
     does not identify any Invariant Sections then there are none.

     The "Cover Texts" are certain short passages of text that are
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
     that says that the Document is released under this License.  A
     Front-Cover Text may be at most 5 words, and a Back-Cover Text may
     be at most 25 words.

     A "Transparent" copy of the Document means a machine-readable copy,
     represented in a format whose specification is available to the
     general public, that is suitable for revising the document
     straightforwardly with generic text editors or (for images
     composed of pixels) generic paint programs or (for drawings) some
     widely available drawing editor, and that is suitable for input to
     text formatters or for automatic translation to a variety of
     formats suitable for input to text formatters.  A copy made in an
     otherwise Transparent file format whose markup, or absence of
     markup, has been arranged to thwart or discourage subsequent
     modification by readers is not Transparent.  An image format is
     not Transparent if used for any substantial amount of text.  A
     copy that is not "Transparent" is called "Opaque".

     Examples of suitable formats for Transparent copies include plain
     ASCII without markup, Texinfo input format, LaTeX input format,
     SGML or XML using a publicly available DTD, and
     standard-conforming simple HTML, PostScript or PDF designed for
     human modification.  Examples of transparent image formats include
     PNG, XCF and JPG.  Opaque formats include proprietary formats that
     can be read and edited only by proprietary word processors, SGML or
     XML for which the DTD and/or processing tools are not generally
     available, and the machine-generated HTML, PostScript or PDF
     produced by some word processors for output purposes only.

     The "Title Page" means, for a printed book, the title page itself,
     plus such following pages as are needed to hold, legibly, the
     material this License requires to appear in the title page.  For
     works in formats which do not have any title page as such, "Title
     Page" means the text near the most prominent appearance of the
     work's title, preceding the beginning of the body of the text.

     A section "Entitled XYZ" means a named subunit of the Document
     whose title either is precisely XYZ or contains XYZ in parentheses
     following text that translates XYZ in another language.  (Here XYZ
     stands for a specific section name mentioned below, such as
     "Acknowledgements", "Dedications", "Endorsements", or "History".)
     To "Preserve the Title" of such a section when you modify the
     Document means that it remains a section "Entitled XYZ" according
     to this definition.

     The Document may include Warranty Disclaimers next to the notice
     which states that this License applies to the Document.  These
     Warranty Disclaimers are considered to be included by reference in
     this License, but only as regards disclaiming warranties: any other
     implication that these Warranty Disclaimers may have is void and
     has no effect on the meaning of this License.

  2. VERBATIM COPYING

     You may copy and distribute the Document in any medium, either
     commercially or noncommercially, provided that this License, the
     copyright notices, and the license notice saying this License
     applies to the Document are reproduced in all copies, and that you
     add no other conditions whatsoever to those of this License.  You
     may not use technical measures to obstruct or control the reading
     or further copying of the copies you make or distribute.  However,
     you may accept compensation in exchange for copies.  If you
     distribute a large enough number of copies you must also follow
     the conditions in section 3.

     You may also lend copies, under the same conditions stated above,
     and you may publicly display copies.

  3. COPYING IN QUANTITY

     If you publish printed copies (or copies in media that commonly
     have printed covers) of the Document, numbering more than 100, and
     the Document's license notice requires Cover Texts, you must
     enclose the copies in covers that carry, clearly and legibly, all
     these Cover Texts: Front-Cover Texts on the front cover, and
     Back-Cover Texts on the back cover.  Both covers must also clearly
     and legibly identify you as the publisher of these copies.  The
     front cover must present the full title with all words of the
     title equally prominent and visible.  You may add other material
     on the covers in addition.  Copying with changes limited to the
     covers, as long as they preserve the title of the Document and
     satisfy these conditions, can be treated as verbatim copying in
     other respects.

     If the required texts for either cover are too voluminous to fit
     legibly, you should put the first ones listed (as many as fit
     reasonably) on the actual cover, and continue the rest onto
     adjacent pages.

     If you publish or distribute Opaque copies of the Document
     numbering more than 100, you must either include a
     machine-readable Transparent copy along with each Opaque copy, or
     state in or with each Opaque copy a computer-network location from
     which the general network-using public has access to download
     using public-standard network protocols a complete Transparent
     copy of the Document, free of added material.  If you use the
     latter option, you must take reasonably prudent steps, when you
     begin distribution of Opaque copies in quantity, to ensure that
     this Transparent copy will remain thus accessible at the stated
     location until at least one year after the last time you
     distribute an Opaque copy (directly or through your agents or
     retailers) of that edition to the public.

     It is requested, but not required, that you contact the authors of
     the Document well before redistributing any large number of
     copies, to give them a chance to provide you with an updated
     version of the Document.

  4. MODIFICATIONS

     You may copy and distribute a Modified Version of the Document
     under the conditions of sections 2 and 3 above, provided that you
     release the Modified Version under precisely this License, with
     the Modified Version filling the role of the Document, thus
     licensing distribution and modification of the Modified Version to
     whoever possesses a copy of it.  In addition, you must do these
     things in the Modified Version:

       A. Use in the Title Page (and on the covers, if any) a title
          distinct from that of the Document, and from those of
          previous versions (which should, if there were any, be listed
          in the History section of the Document).  You may use the
          same title as a previous version if the original publisher of
          that version gives permission.

       B. List on the Title Page, as authors, one or more persons or
          entities responsible for authorship of the modifications in
          the Modified Version, together with at least five of the
          principal authors of the Document (all of its principal
          authors, if it has fewer than five), unless they release you
          from this requirement.

       C. State on the Title page the name of the publisher of the
          Modified Version, as the publisher.

       D. Preserve all the copyright notices of the Document.

       E. Add an appropriate copyright notice for your modifications
          adjacent to the other copyright notices.

       F. Include, immediately after the copyright notices, a license
          notice giving the public permission to use the Modified
          Version under the terms of this License, in the form shown in
          the Addendum below.

       G. Preserve in that license notice the full lists of Invariant
          Sections and required Cover Texts given in the Document's
          license notice.

       H. Include an unaltered copy of this License.

       I. Preserve the section Entitled "History", Preserve its Title,
          and add to it an item stating at least the title, year, new
          authors, and publisher of the Modified Version as given on
          the Title Page.  If there is no section Entitled "History" in
          the Document, create one stating the title, year, authors,
          and publisher of the Document as given on its Title Page,
          then add an item describing the Modified Version as stated in
          the previous sentence.

       J. Preserve the network location, if any, given in the Document
          for public access to a Transparent copy of the Document, and
          likewise the network locations given in the Document for
          previous versions it was based on.  These may be placed in
          the "History" section.  You may omit a network location for a
          work that was published at least four years before the
          Document itself, or if the original publisher of the version
          it refers to gives permission.

       K. For any section Entitled "Acknowledgements" or "Dedications",
          Preserve the Title of the section, and preserve in the
          section all the substance and tone of each of the contributor
          acknowledgements and/or dedications given therein.

       L. Preserve all the Invariant Sections of the Document,
          unaltered in their text and in their titles.  Section numbers
          or the equivalent are not considered part of the section
          titles.

       M. Delete any section Entitled "Endorsements".  Such a section
          may not be included in the Modified Version.

       N. Do not retitle any existing section to be Entitled
          "Endorsements" or to conflict in title with any Invariant
          Section.

       O. Preserve any Warranty Disclaimers.

     If the Modified Version includes new front-matter sections or
     appendices that qualify as Secondary Sections and contain no
     material copied from the Document, you may at your option
     designate some or all of these sections as invariant.  To do this,
     add their titles to the list of Invariant Sections in the Modified
     Version's license notice.  These titles must be distinct from any
     other section titles.

     You may add a section Entitled "Endorsements", provided it contains
     nothing but endorsements of your Modified Version by various
     parties--for example, statements of peer review or that the text
     has been approved by an organization as the authoritative
     definition of a standard.

     You may add a passage of up to five words as a Front-Cover Text,
     and a passage of up to 25 words as a Back-Cover Text, to the end
     of the list of Cover Texts in the Modified Version.  Only one
     passage of Front-Cover Text and one of Back-Cover Text may be
     added by (or through arrangements made by) any one entity.  If the
     Document already includes a cover text for the same cover,
     previously added by you or by arrangement made by the same entity
     you are acting on behalf of, you may not add another; but you may
     replace the old one, on explicit permission from the previous
     publisher that added the old one.

     The author(s) and publisher(s) of the Document do not by this
     License give permission to use their names for publicity for or to
     assert or imply endorsement of any Modified Version.

  5. COMBINING DOCUMENTS

     You may combine the Document with other documents released under
     this License, under the terms defined in section 4 above for
     modified versions, provided that you include in the combination
     all of the Invariant Sections of all of the original documents,
     unmodified, and list them all as Invariant Sections of your
     combined work in its license notice, and that you preserve all
     their Warranty Disclaimers.

     The combined work need only contain one copy of this License, and
     multiple identical Invariant Sections may be replaced with a single
     copy.  If there are multiple Invariant Sections with the same name
     but different contents, make the title of each such section unique
     by adding at the end of it, in parentheses, the name of the
     original author or publisher of that section if known, or else a
     unique number.  Make the same adjustment to the section titles in
     the list of Invariant Sections in the license notice of the
     combined work.

     In the combination, you must combine any sections Entitled
     "History" in the various original documents, forming one section
     Entitled "History"; likewise combine any sections Entitled
     "Acknowledgements", and any sections Entitled "Dedications".  You
     must delete all sections Entitled "Endorsements."

  6. COLLECTIONS OF DOCUMENTS

     You may make a collection consisting of the Document and other
     documents released under this License, and replace the individual
     copies of this License in the various documents with a single copy
     that is included in the collection, provided that you follow the
     rules of this License for verbatim copying of each of the
     documents in all other respects.

     You may extract a single document from such a collection, and
     distribute it individually under this License, provided you insert
     a copy of this License into the extracted document, and follow
     this License in all other respects regarding verbatim copying of
     that document.

  7. AGGREGATION WITH INDEPENDENT WORKS

     A compilation of the Document or its derivatives with other
     separate and independent documents or works, in or on a volume of
     a storage or distribution medium, is called an "aggregate" if the
     copyright resulting from the compilation is not used to limit the
     legal rights of the compilation's users beyond what the individual
     works permit.  When the Document is included an aggregate, this
     License does not apply to the other works in the aggregate which
     are not themselves derivative works of the Document.

     If the Cover Text requirement of section 3 is applicable to these
     copies of the Document, then if the Document is less than one half
     of the entire aggregate, the Document's Cover Texts may be placed
     on covers that bracket the Document within the aggregate, or the
     electronic equivalent of covers if the Document is in electronic
     form.  Otherwise they must appear on printed covers that bracket
     the whole aggregate.

  8. TRANSLATION

     Translation is considered a kind of modification, so you may
     distribute translations of the Document under the terms of section
     4.  Replacing Invariant Sections with translations requires special
     permission from their copyright holders, but you may include
     translations of some or all Invariant Sections in addition to the
     original versions of these Invariant Sections.  You may include a
     translation of this License, and all the license notices in the
     Document, and any Warrany Disclaimers, provided that you also
     include the original English version of this License and the
     original versions of those notices and disclaimers.  In case of a
     disagreement between the translation and the original version of
     this License or a notice or disclaimer, the original version will
     prevail.

     If a section in the Document is Entitled "Acknowledgements",
     "Dedications", or "History", the requirement (section 4) to
     Preserve its Title (section 1) will typically require changing the
     actual title.

  9. TERMINATION

     You may not copy, modify, sublicense, or distribute the Document
     except as expressly provided for under this License.  Any other
     attempt to copy, modify, sublicense or distribute the Document is
     void, and will automatically terminate your rights under this
     License.  However, parties who have received copies, or rights,
     from you under this License will not have their licenses
     terminated so long as such parties remain in full compliance.

 10. FUTURE REVISIONS OF THIS LICENSE

     The Free Software Foundation may publish new, revised versions of
     the GNU Free Documentation License from time to time.  Such new
     versions will be similar in spirit to the present version, but may
     differ in detail to address new problems or concerns.  See
     `http://www.gnu.org/copyleft/'.

     Each version of the License is given a distinguishing version
     number.  If the Document specifies that a particular numbered
     version of this License "or any later version" applies to it, you
     have the option of following the terms and conditions either of
     that specified version or of any later version that has been
     published (not as a draft) by the Free Software Foundation.  If
     the Document does not specify a version number of this License,
     you may choose any version ever published (not as a draft) by the
     Free Software Foundation.

A.1.1 ADDENDUM: How to use this License for your documents
----------------------------------------------------------

To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:

       Copyright (C)  YEAR  YOUR NAME.
       Permission is granted to copy, distribute and/or modify this document
       under the terms of the GNU Free Documentation License, Version 1.2
       or any later version published by the Free Software Foundation;
       with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
       A copy of the license is included in the section entitled ``GNU
       Free Documentation License''.

   If you have Invariant Sections, Front-Cover Texts and Back-Cover
Texts, replace the "with...Texts." line with this:

         with the Invariant Sections being LIST THEIR TITLES, with
         the Front-Cover Texts being LIST, and with the Back-Cover Texts
         being LIST.

   If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.

   If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License, to
permit their use in free software.

