Doc updates for server connection dialogue and related info.

docs/en_US/pgadmin_tabbed_browser.rst

@@ -4,46 +4,44 @@
 The pgAdmin Tabbed Browser 
 **************************
 
-The right pane of the *pgAdmin* window features a collection of tabs that display information about the object currently selected in the *pgAdmin* tree control in the left window.  
-   
-Permanent tabs are named *Dashboard, *Properties*, *SQL*, *Statistics*, *Dependencies* and *Dependents*; each tab may be repositioned as a floating window. Select a tab to access information about the highlighted object in the tree control. 
+The right pane of the *pgAdmin* window features a collection of tabs that display information about the object currently selected in the *pgAdmin* tree control in the left window.  Select a tab to access information about the highlighted object in the tree control. 
 
 .. image:: images/main_dashboard.png 
 
-The *Dashboard* tab provides a graphical analysis of the usage statistics for the selected server or database:
+The graphs on the *Dashboard* tab provides an active analysis of the usage statistics for the selected server or database:
 
 * The *Server sessions* or *Database sessions* graph displays the interactions with the server or database.
 * The *Transactions per second* graph displays the commits, rollbacks, and total transactions per second that are taking place on the server or database.
-* The *Tuples In* graph displays the number of tuples inserted, updated, and deleted on the server or database.
+* The *Tuples in* graph displays the number of tuples inserted, updated, and deleted on the server or database.
 * The *Tuples out* graph displays the number of tuples fetched and returned from the server or database.
 * The *Block I/O* graph displays the number of blocks read from the filesystem or fetched from the buffer cache (but not the operating system's file system cache) for the server or database.
 
-The *Server activity* panel displays information about sessions, locks, prepared transactions and configuration. The information is presented in context-sensitive tables.
+The *Server activity* panel displays information about sessions, locks, prepared transactions, and server configuration (if applicable). The information is presented in context-sensitive tables.  Use controls located above the table to:
 
-Click the *Properties* tab to continue.
+* Click the *Refresh* button to update the information displayed in each table.
+* Enter a value in the *Search* box to restrict the table content to one or more sessions that satisfy the search criteria.  For example, you can enter a process ID to locate a specific session, or a session state (such as *idle*) to locate all of the sessions that are in an idle state.
+
+You can use icons in the *Sessions* table to review or control the state of a session:
+
+* Use the *Terminate* icon (located in the first column) to stop a session and remove the session from the table.  Before the server terminates the session, you will be prompted to confirm your selection.
+* Use the *Cancel* icon (located in the second column) to terminate an active query without closing the session.  Before canceling the query, the server will prompt you to confirm your selection.  When you cancel a query, the value displayed in the *State* column of the table will be updated from *Active* to *Idle*.  The session will remain in the table until the session is terminated.
+* Use the *Details* icon (located in the third column) to open the *Details* tab; the tab displays information about the selected session. 
 
 .. image:: images/main_properties_table.png
 
-Review properties on expandable windows specific to the *Object* selected. If multiple boxes are displayed, you can click the arrow to the left on the blue bar at the top of each box:
-
- * Point the arrow to the right to contract the box.
- * Point the arrow down to expand the window. 
-
-.. image:: images/main_properties_edit.png 
-
-Click the *Edit* icon in the toolbar under the browser tabs to launch a dialog. 
+The *Properties* tab displays information about the object selected. Click the *Edit* icon in the toolbar under the browser tabs to launch the *Properties* dialog for the selected object. 
 
 .. image:: images/main_properties_icons.png
 
-If you change properties in the opened dialog, save your work. The *Properties* tab updates to show recent modifications. 
+To preserve any changes to the *Properties* dialog, click the *Save* icon; your modifications will be displayed in the updated *Properties* tab. 
 
-Click the *SQL* tab to continue.
+.. image:: images/main_properties_edit.png 
+
+Details about the object highlighted in the tree control are displayed in one or more collapsible panels. You can use the arrow to the left of each panel label to open or close a panel.
 
 .. image:: images/main_sql.png
 
-The SQL pane on the *SQL* tab contains an SQL script that creates the highlighted object, and if applicable, a (commented out) SQL statement that will *DROP* the selected object. You can copy the SQL statements to an editor of your choice using cut & paste shortcuts.
-
-Click the *Statistics* tab to continue.
+The *SQL* tab displays the SQL script that created the highlighted object, and when applicable, a (commented out) SQL statement that will *DROP* the selected object. You can copy the SQL statements to the editor of your choice using cut and paste shortcuts.
 
 .. image:: images/main_statistics.png
 
@@ -103,11 +101,9 @@ The *Statistics* tab displays the statistics gathered for each object on the tre
 | *Size*                     | displays the size (in megabytes) of the selected database.                                                 |
 +----------------------------+------------------------------------------------------------------------------------------------------------+
 
-Click the *Dependencies* tab to continue.
-
 .. image:: images/main_dependencies.png 
 
-The *Dependencies* tab displays the objects on which the currently selected object depends. If a dependency is dropped, the object currently selected in the pgAdmin tree control will be affected. To ensure the integrity of the entire database structure, the database server makes sure that you do not accidentally drop objects that other objects depend on; you must use DROP CASCADE to remove an object with a dependency.
+The *Dependencies* tab displays the objects on which the currently selected object depends. If a dependency is dropped, the object currently selected in the pgAdmin tree control will be affected. To ensure the integrity of the entire database structure, the database server makes sure that you do not accidentally drop objects that other objects depend on; you must use the DROP CASCADE command to remove an object with a dependency.
 
 The *Dependencies* table displays the following information:
 
@@ -119,8 +115,6 @@ The *Dependencies* table displays the following information:
    * If the field is *normal*, the selected object can be dropped without dropping the parent object.
    * If the field is *blank*, the selected object is required by the system, and cannot be dropped.
      
-Click the *Dependents* tab to continue.
-
 .. image:: images/main_dependents.png
 
 The *Dependents* tab displays a table of objects that depend on the object currently selected in the *pgAdmin* browser. A dependent object can be dropped without affecting the object currently selected in the *pgAdmin* tree control.
@@ -129,9 +123,8 @@ The *Dependents* tab displays a table of objects that depend on the object curre
 * The *Name* field specifies the identifying name for the dependent object.
 * The *Database* field specifies the database in which the object resides.
 
-**Feature Tabs**
-
-Additional *feature tabs* will open in the *pgAdmin* tabbed browser when you access the extended functionality offered by pgAdmin tools. For example, if you select the *Query tool* from *Tools* in the menu bar, pgAdmin will open the Query tool on a tab labeled *Query-1*. These feature tabs are not permanent and you can close them when you are finished using the tool. Like permanent tabs, these tabs may be repositioned.
-
 .. image:: images/main_query_tool.png
 
+Additional tabs open when you access the extended functionality offered by pgAdmin tools (such as the Query tool, Debugger, or SQL editor). Use the close icon (X) located in the upper-right corner of each tab to close the tab when you are finished using the tool. Like permanent tabs, these tabs may be repositioned in the pgAdmin client window.
+
+By default, each time you open a tool, pgAdmin will open a new browser tab. You can control this behavior by modifying the *Display* node of the *Preferences* dialog for each tool. To open the *Preferences* dialog, select *Preferences* from the *File* menu.

docs/en_US/server_dialog.rst

@@ -4,22 +4,17 @@
 The Server Dialog
 *****************
 
-Use the *Server* dialog to describe a connection to a server. Note: you must ensure the pg_hba.conf file of the server
-from which you are connecting allows connections from the host of the client.
-
-The *Server* dialog organizes the connection of a server through the following dialog tabs: *General*, and *Connection*.
+Use the *Server* dialog to describe a connection to a server. Note: you must ensure that the pg_hba.conf file of the server from which you are connecting allows connections from the host of the client.
 
 .. image:: images/server_general.png
 
 Use the fields in the *General* tab to identify the server:
 
-* Use the *Name* field to add a descriptive name for the server; the name specified will be displayed in the *pgAdmin*
-  tree control of the client.
-* Use the drop-down list box in the *Server group* field to specify the *pgAdmin* tree control parent node for the server.
+* Use the *Name* field to add a descriptive name for the server; the name specified will be displayed in the *Browser* tree control.
+* Use the drop-down list box in the *Server group* field to select the parent node for the server; the server will be displayed in the *Browser* tree control within the specified group.
 * Use the color-picker in the *Background* field to specify the background color for the server.
 * Use the color-picker in the *Foreground* field to specify the foreground color for the server.
-* Uncheck the checkbox next to *Connect now?* to instruct pgAdmin not to attempt a connection upon completion of the
-  dialog. The default enables connection.
+* If the *Connect now?* checkbox is checked, the client will attempt a connection to the server upon completion of the dialog; this is the default
 * Provide a comment about the server in the *Comments* field.
 
 Click the *Connection* tab to continue.
@@ -28,55 +23,31 @@ Click the *Connection* tab to continue.
 
 Use the fields in the *Connection* tab to configure a connection:
 
-* Specify the IP address of the server host, or the fully qualified domain name in the *Host name/address* field. On
-  Unix based systems, the address field may be left blank to use the default PostgreSQL Unix Domain Socket on the local
-  machine, or may be set to an alternate path containing a PostgreSQL socket. If you enter a path, the path must begin
-  with a "/".
+* Specify the IP address of the server host, or the fully qualified domain name in the *Host name/address* field. On Unix based systems, the address field may be left blank to use the default PostgreSQL Unix Domain Socket on the local machine, or may be set to an alternate path containing a PostgreSQL socket. If you enter a path, the path must begin with a "/".
 * Enter the listener port number of the server host in the *Port* field. The default is *5432*.
-* Use the *Maintenance database* field to specify the name of the initial database to which the client will connect.
-  If you will be using pgAgent or adminpack objects, the pgAgent schema and adminpack objects should be installed on that
-  database.
-* Use the *User name* field to specify the name of a role that will be used when authenticating with the server.
+* Use the *Maintenance database* field to specify the name of the initial database to which the client will connect. If you will be using pgAgent or adminpack objects, the pgAgent schema and adminpack objects should be installed on that database.
+* Use the *Username* field to specify the name of a role that will be used when authenticating with the server.
 * Use the *Password* field to provide a password that will be supplied when authenticating with the server.
-* Check the box next to *Save password* to instruct pgAdmin to save the password for future use.
-* Use the *Role* field to specify the name of a role that has privileges that will be conveyed to the client after
-  authentication with the server. This selection allows you to connect as one role, and then assume the permissions of
-  this specified role after the connection is established. Note that the connecting role must be a member of the role
-  specified.
+* Check the box next to *Save password?* to instruct pgAdmin to save the password for future use.
+* Use the *Role* field to specify the name of a role that has privileges that will be conveyed to the client after authentication with the server. This selection allows you to connect as one role, and then assume the permissions of this specified role after the connection is established. Note that the connecting role must be a member of the role specified.
 
 Click the *SSL* tab to continue.
 
 .. image:: images/server_ssl.png
 
-Use the fields in the *SSL* tab to configure a SSL:
+Use the fields in the *SSL* tab to configure SSL:
 
-* Use the drop-down list box in the SSL field to select the type of SSL connection the server should use. For more
-  information about using SSL encryption, see Section 31.18 of the Postgres documentation:
+* Use the drop-down list box in the *SSL* field to select the type of SSL connection the server should use. For more information about using SSL encryption, see Section 33.18 of the `Postgres documentation <https://www.postgresql.org/docs/current/static/libpq-ssl.html>`_.
 
-   http://www.postgresql.org/docs/9.5/static/libpq-ssl.html
+If pgAdmin is installed in Server mode (the default mode), you can use the platform-specific File manager dialog to upload files that support SSL encryption to the server.  To access the File manager dialog, click the icon that is located to the right of each of the following fields.
 
-* Specify the file containing the name of the client SSL certificate, replacing the default *~/.postgresql/postgresql.crt*
-  in case of Desktop mode and *<STORAGE_DIR>/<USERNAME>/.postgresql/postgresql.crt* in case of Web mode. This parameter
-  is ignored if an SSL connection is not made.
-* Specify the file containing the secret key used for the client certificate, replacing the default *~/.postgresql/postgresql.key*
-  in case of Desktop mode and *<STORAGE_DIR>/<USERNAME>/.postgresql/postgresql.key* in case of Web mode. This parameter
-  is ignored if an SSL connection is not made.
-* Specify the file containing the SSL certificate authority, replacing the default *~/.postgresql/root.crt*. This
-  parameter is ignored if an SSL connection is not made.
-* Specify the file containing the SSL certificate revocation list, replacing the default *~/.postgresql/root.crl*. This
-  parameter is ignored if an SSL connection is not made.
-* If set to True, data sent over SSL connections will be compressed else compression will be disabled, The default
-  is *False*. This parameter is ignored if an SSL connection is not made, see Section 32.1.2 of the Postgres documentation
-  for more details:
+* Use the *Client certificate* field to specify the file containing the client SSL certificate.  This file will replace the default *~/.postgresql/postgresql.crt* if pgAdmin is installed in Desktop mode, and *<STORAGE_DIR>/<USERNAME>/.postgresql/postgresql.crt* if pgAdmin is installed in Web mode. This parameter is ignored if an SSL connection is not made.
+* Use the *Client certificate key* field to specify the file containing the secret key used for the client certificate.  This file will replace the default *~/.postgresql/postgresql.key* if pgAdmin is installed in Desktop mode, and *<STORAGE_DIR>/<USERNAME>/.postgresql/postgresql.key* if pgAdmin is installed in Web mode. This parameter is ignored if an SSL connection is not made.
+* Use the *Root certificate* field to specify the file containing the SSL certificate authority.  This file will replace the default *~/.postgresql/root.crt*. This parameter is ignored if an SSL connection is not made.
+* Use the *Certificate revocation list* field to specify the file containing the SSL certificate revocation list.  This list will replace the default list, found in *~/.postgresql/root.crl*. This parameter is ignored if an SSL connection is not made.
+* When *SSL compression?* is set to *True*, data sent over SSL connections will be compressed.  The default value is *False* (compression is disabled).  This parameter is ignored if an SSL connection is not made.
 
-In Server mode, files can be uploaded to the server using the File chooser dialog.
-
-   https://www.postgresql.org/docs/9.6/static/libpq-connect.html
-
-*WARNING:* In Server mode, certificates, private keys and the revocation list are stored in the per-user file storage
-area on the server, which is owned by the user account under which the pgAdmin server process is run. This means that
-administrators of the server may be able to access those files, so appropriate caution should be taken before choosing
-to use this feature.
+*WARNING:* In Server mode, certificates, private keys, and the revocation list are stored in the per-user file storage area on the server, which is owned by the user account under which the pgAdmin server process is run. This means that administrators of the server may be able to access those files; appropriate caution should be taken before choosing to use this feature.
 
 Click the *Advanced* tab to continue.
 
@@ -84,18 +55,12 @@ Click the *Advanced* tab to continue.
 
 Use the fields in the *Advanced* tab to configure a connection:
 
-* Specify the IP address of the server host. Using this field to specify the host IP address will avoid a DNS lookup on
-  connection, however it may be useful to specify both a host name and address when using Kerberos, GSSAPI, or SSPI
-  authentication methods, as well as for verify-full SSL certificate verification
-* The DB restriction field allows you to enter an SQL restriction that will be used against the pg_database table to
-  limit the databases that you see. For example, you might enter: *live_db test_db* so that only live_db and test_db are
-  shown in the pgAdmin browser. Separate entries with a comma or tab as you type.
-* Specify the password file which allow user to login without providing password, see Section 33.15 of the Postgres documentation:
-
-   https://www.postgresql.org/docs/current/static/libpq-pgpass.html
+* Specify the IP address of the server host in the *Host address* field. Using this field to specify the host IP address may save time by avoiding a DNS lookup on connection, but it may be useful to specify both a host name and address when using Kerberos, GSSAPI, or SSPI authentication methods, as well as for verify-full SSL certificate verification.
+* Use the *DB restriction* field to provide a SQL restriction that will be used against the pg_database table to limit the databases that you see. For example, you might enter: *live_db test_db* so that only live_db and test_db are shown in the pgAdmin browser. Separate entries with a comma or tab as you type.
+* Use the *Password File* field to specify the location of a password file (.pgpass). A .pgpass file allows a user to login without providing a password when they connect.  For more information, see Section 33.15 of the `Postgres documentation <http://www.postgresql.org/docs/current/static/libpq-pgpass.html>`_.
 
 *NOTE:* The password file option is only supported when pgAdmin is using libpq v10.0 or later to connect to the server.
 
-* Click the *Save* button to save work.
-* Click the *Cancel* button to exit without saving work.
-* Click the *Reset* button to restore configuration parameters.
+* Click the *Save* button to save your work.
+* Click the *Cancel* button to exit without saving your work.
+* Click the *Reset* button to return the values specified on the Server dialog to their original condition.