Shorten SQL mode NEWS entry, moving more details to doc strings

* lisp/progmodes/sql.el (sql-port, sql-connection-alist, sql-list-all)
(sql-list-table): Doc fixes.
* etc/NEWS: Related edits.

3 files changed, 40 insertions, 54 deletions

diff --git a/etc/NEWS b/etc/NEWS
index 5cdf92d91fb..07b9db9989f 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -781,63 +781,50 @@ directory is a remote file name and neither the environment variable
 $ESHELL nor the variable `explicit-shell-file-name' is set.
 
 ---
-** SQL Mode enhancements.
+** SQL mode
 
-*** `sql-dialect' is an alias for `sql-product'.
+---
+*** New options `sql-port', `sql-connection-alist', `sql-send-terminator',
+and `sql-oracle-scan-on'.
 
-*** New variable `sql-port' specifies the port number for connecting
-to a MySQL or Postgres server.
+---
+*** New custom variables control prompting for login parameters.
+Each supported product has a custom variable `sql-*-login-params',
+which is a list of the parameters to be prompted for before a
+connection is established.
 
+---
 *** The command `sql-product-interactive' now takes a prefix argument,
-which causes it to prompt for an SQL product instead of the current
-value of `sql-product'.
+which causes it to prompt for an SQL product.
 
-*** Product-specific SQL interactive commands now take prefix args.
+---
+*** Product-specific SQL interactive commands now take prefix arguments.
 These commands (`sql-sqlite', `sql-postgres', `sql-mysql', etc.),
 given a prefix argument, prompt for a name for the SQL interactive
 buffer.  This reduces the need for calling `sql-rename-buffer'.
 
+---
 *** SQL interactive modes suppress command continuation prompts, and
 replace tabs with spaces.  The first change impacts multiple line SQL
 statements entered with C-j between each line, statements yanked into
 the buffer and statements sent with `sql-send-*' functions.  The
-second change prevents the MySQL and Postgres interpreters from
-listing object name completions when sent text via `sql-send-*'
-functions.
-
-*** New custom variables control prompting for login parameters.
-Each supported product has a custom variable `sql-*-login-params',
-which is a list of the parameters to be prompted for before a
-connection is established.
-
-*** New variable `sql-connection-alist' for login parameter values.
-This can be used to store different username, database and server
-values.  Connections defined in this variable appear in the submenu
-SQL->Start... for making new SQLi sessions.
+second prevents the MySQL and Postgres interpreters from listing
+object name completions when sent text via `sql-send-*' functions.
 
+---
 *** New command `sql-connect' starts a predefined SQLi session,
 using the login parameters from `sql-connection-alist'.
 
+---
 *** New "Save Connection" menu item in SQLi buffers.
 This gathers the login params specified for the SQLi session, if it
 was not started by a connection, and saves them as a new connection.
 
-*** Commands for listing database objects and details.
-In an SQLi session, you can get a list of objects in the database.
-The contents of these lists are product specific.
-
-**** `C-c C-l a' or the "SQL->List all objects" menu item
-lists all the objects in the database.  With a prefix argument, it
-displays additional details or extend the listing to include other
-schemas objects.
-
-**** `C-c C-l t' or the "SQL->List Table details" menu item
-prompts for the name of a database table or view and displays the list
-of columns in the relation.  With a prefix argument, it displays
-additional details about each column.
-
-*** New options `sql-send-terminator' and `sql-oracle-scan-on'.
+---
+*** New commands for listing database objects and details:
+sql-list-all and sql-list-table.
 
+---
 *** An API for manipulating SQL product definitions has been added.
 
 ** TeX modes
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index e8ed552ba07..9cda0d38acb 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,5 +1,8 @@
 2012-02-08  Glenn Morris  <rgm@gnu.org>
 
+        * progmodes/sql.el (sql-port, sql-connection-alist, sql-list-all)
+        (sql-list-table): Doc fixes.
+
         * image-mode.el (image-transform-minor-mode-map, image-transform-mode):
         Comment out (does nothing).
 
diff --git a/lisp/progmodes/sql.el b/lisp/progmodes/sql.el
index 2e59d8f8517..f8f62d113e6 100644
--- a/lisp/progmodes/sql.el
+++ b/lisp/progmodes/sql.el
@@ -285,7 +285,7 @@ Customizing your password will store it in your ~/.emacs file."
   :safe 'stringp)
 
 (defcustom sql-port 0
-  "Default port."
+  "Default port for connecting to a MySQL or Postgres server."
   :version "24.1"
   :type 'number
   :group 'SQL
@@ -613,30 +613,22 @@ settings.")
   '(:font-lock :sqli-program :sqli-options :sqli-login :statement))
 
 (defcustom sql-connection-alist nil
-  "An alist of connection parameters for interacting with a SQL
-  product.
-
+  "An alist of connection parameters for interacting with a SQL product.
 Each element of the alist is as follows:
 
   \(CONNECTION \(SQL-VARIABLE VALUE) ...)
 
 Where CONNECTION is a symbol identifying the connection, SQL-VARIABLE
 is the symbol name of a SQL mode variable, and VALUE is the value to
-be assigned to the variable.
-
-The most common SQL-VARIABLE settings associated with a connection
-are:
-
-  `sql-product'
-  `sql-user'
-  `sql-password'
-  `sql-port'
-  `sql-server'
-  `sql-database'
+be assigned to the variable.  The most common SQL-VARIABLE settings
+associated with a connection are: `sql-product', `sql-user',
+`sql-password', `sql-port', `sql-server', and `sql-database'.
 
 If a SQL-VARIABLE is part of the connection, it will not be
-prompted for during login."
-
+prompted for during login.  The command `sql-connect' starts a
+predefined SQLi session using the parameters from this list.
+Connections defined here appear in the submenu SQL->Start...  for
+making new SQLi sessions."
   :type `(alist :key-type (string :tag "Connection")
                 :value-type
                 (set
@@ -3647,7 +3639,9 @@ The list is maintained in SQL interactive buffers.")
       (read-from-minibuffer prompt tname))))
 
 (defun sql-list-all (&optional enhanced)
-  "List all database objects."
+  "List all database objects.
+With optional prefix argument ENHANCED, displays additional
+details or extends the listing to include other schemas objects."
   (interactive "P")
   (let ((sqlbuf (sql-find-sqli-buffer)))
     (unless sqlbuf
@@ -3659,7 +3653,9 @@ The list is maintained in SQL interactive buffers.")
       (set (make-local-variable 'sql-buffer) sqlbuf))))
 
 (defun sql-list-table (name &optional enhanced)
-  "List the details of a database table. "
+  "List the details of a database table named NAME.
+Displays the columns in the relation.  With optional prefix argument
+ENHANCED, displays additional details about each column."
   (interactive
    (list (sql-read-table-name "Table name: ")
          current-prefix-arg))