  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 1, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.


  CHANGE LOG
  ====== ===
 
  05/13/05 dnizhego - added better comments for installaton
                      done before font-lock-keywords are set
  05/12/05 dnizhego - newer versions of emacs require that run-hooks is
                      done before font-lock-keywords are set
  04/10/97 dnizhego - added prelimiary support for SQL DDL CREATE OR REPLACE
  04/09/97 dnizhego - wrote new case-adjust driver -- from 
                      super slow to super fast !!!
  04/08/97 dnizhego - fixed adjacent keyword (e.g. IN OUT) problem on FSF
  04/08/97 dnizhego - fixed /**/-comment problems on FSF Emacs
  03/19/97 dnizhego - added decoration scaling for GNU Emacs.
  03/19/97 dnizhego - enabled highlighting under GNU Emacs
  03/19/97 dnizhego - fixed case-adjust under GNU Emacs.
  11/07/96 dnizhego - fixed indenter
  08/15/96 dnizhego - added few more keywords
  03/29/96 dnizhego - most regexp generation goes eval-when-compile
  03/27/96 dnizhego - fixed buffer case adjuster (C-c C-b)
  03/23/96 dnizhego - aded STANDARD keywords, names containing # abd $
  03/06/96 dnizhego - added style menue
  02/15/96 dnizhego - version 1.1: using SRX, added most "hard" PLS syntax
  01/11/96 dnizhego - version 1.0 created


 Initially derived from ada-mode.el, (C) 1994-1995 by 
 Markus Heritsch <Markus.Heritsch@studbox.uni-stuttgart.de> and
 Rolf Ebert      <ebert@inf.enst.fr>

 INSTALLATION and USAGE
 ======================

 To start using PLS-MODE, download files pls-mode.el and
 structured-regexp.el into any directory that is in your
 load-path. To see which directories are on your load-path, type
 M-x load-path. You can byte-compile the files for better speed.

 To enable PLS-MODE, add the following lines to your .emacs file:

 (autoload 'pls-mode  "pls-mode" "PL/SQL Editing Mode" t)
 (autoload 'diana-mode  "pls-mode" "DIANA for PL/SQL Browsing Mode" t)
 (setq auto-mode-alist
   (append '(("\\.pls$"  . pls-mode)
             ("\\.sql$"  . pls-mode)
             ("\\.pld$"  . diana-mode)
            ) auto-mode-alist))
 (setq pls-mode-hook '(lambda () (font-lock-mode 1))) 

 To toggle the highlighting type M-x font-lock-mode.

 When you have entered pls-mode, you wiil get both pull-down and
 pop-up PL/SQL menu. You may get more info about the mode and key
 bindings by pressing C-h m. You may also get online help
 describing various functions by: C-h d name-of-function


 FEATURES
 ========

 PLS mode helps you to properly indent and case-adjust PL/SQL code
 while you type it.  For instance, typing

      declare
      x integer; 
      y number;
      begin 
      x := y;
      end;

 would result in 

      DECLARE
         x INTEGER; 
         y NUMBER;
      BEGIN 
         x := y;
      END;

 Additionally, the code will be decorated with fonts and colors.
 PLS mode uses 4 distinct "faces" to decorate the following elements
 of PL/SQL programs: keywords, comments, definitions, strings.
 See 'font-lock-mode' for more details.

 PLS mode recognizes all SQL keywords and PL/SQL reserved names and
 keywords, and understands other elements of PL/SQL syntax - comments, 
 strings, double-quoted names, etc.

 When in .pls file, use button3 to pop up the menu of PLS-specific
 commands. Alternatively, the same menu can be pulled out the manu-bar.

 Icon-lovers and Word-heads: no PLS XEmacs icons provided so far.  Send
 your favorite xpm files to dnizhego@us.oracle.com.

 Most of the entries on PLS popup menu are annotated with "hot key"
 combinations - you may find it convenient to learn these key
 bindins over time.

 PLS mode supports automatic case-adjusting and font-highlighting.
 There are 3 styles the user can choose from (see
 PLS pop-up menu):

 Official - as in Oracle SQL & PL/SQL user guide:
        DECLARE mynum NUMBER; BEGIN  mynum := mynum + 1; END;
 Classical - as in algol, pascal or ADA literature:
        declare MYNUM number; begin  MYNUM := MYNUM + 1; end;
 Contemporary (identifiers are capitalized):
        declare MyNum number; begin  MyNum := MyNum + 1; end;
 Budget - everything lowercased.

 After switching to another style, type C-c C-b or use menu entry
 "Adjust Case Buffer" to propagate the style.

 The dafault style is Official.

 The automatic case-adjusting can be toggled on/of from the pop-up
 menu. By default, the automatic case-adjusting is ON.

 COMMENTARY
 ==========

 This packages is derived from XEmacs Ada mode written by
 M. Heritsch and R. Ebert. 

 Althoug PLSQL closely resembles ADA, there are many subtle
 differences between the two languages, making the direct use of
 ADA mode very difficult. Among the things that confuse any ADA
 mode: %-delimited type-modifying attributes, ()-grouped
 record/type attributes, separated with ",", hanging toplevel "/",
 C-style comments, "pls 2quoted names", embedded SQL just to
 mention few. IN addition, PLSQL carries its own set of reserved
 words and keywords and a hearty supply of SQL keywords.

 In the current version of PLS mode, complex regesps are handled
 with the Structured Regexp package.  Some existing bugs are fixed,
 the pretty-printer can work even in absence of an external
 formatting tool, although the performance leaves a lot to
 desire. 

 Some ADA constucts that never made it into PL/SQL (tasks,
 generics) are still "supported" and may affect certain PLSQL
 constructs. Please report such atavisms to dnizhego@us.oracle.com



 FUTURE
 =======

 We plan to extend this package in several directions:
 - improve speed
 - support C-M-[fb] that jump between matching begin/else if/then/else[if]
 - add flags for versions of PLS.
 - support `compile-buffer' `compile-line', `comile-region'
 - support simultaneous browsing of .pls .pld files.
 - better design of the pop-up/menu-bar menues.
 - more support for DIANA files ( *.pld)
 - add support for other pls-compier-generated formats (.plm, etc)
 - add support for SQL files (*.sql)

 PROBLEMS
 ==========
 
 1. Many ADA constructs not supported by PL/SQL are still recognized,
 which may affect appearance of some PLSQL code.
 Just to name few: tasks, generics, private, limited.
 
 2. Trailing ")" if placed on a separate line, will be indented
 up to "(", regardless what is the value of `pls-indent-to-open-paren'
 
 define TYPE emp_ad (
   idxn NUMBER,
   sal VARCHAR2(20)  <----- put it here instead !!
 -wh-o-o-o------->  );

 In the presence of comments and/or incorrect syntax
 pls-format-paramlist produces weird results.


 3. Comments at the very beginning of the buffer (_before_ any
 code) are not indented to the left and not aligned with comments
 above.  Also, the very first top-level form can be positioned
 "freely" and will not be forced to the left by the indenter.
 Thus, it is possible to justify the contents of the whole buffer
 to the rigth by shifting the very first code line and then C-c
 C-p.  Consider this a bug or a feature?


 RANDOM ISSUES
 ====== ======  

 For those who is working with PL/SQL examples from an excellent
 book `ORACLE PL/SQL Programming" by Steven Feuerstein.

 By adding this to your .emacs file you'll automatically 
 bring pls mode when opening each of pls/sql files from the
 companion floppy:

 (setq auto-mode-alist
   (append 
    '(
 	 ("\\.ff$" . pls-mode)  ;; Oracle Forms function 
 	 ("\\.fp$" . pls-mode)  ;; Oracle Forms procedure 
 	 ("\\.fpp$" . pls-mode) ;; Oracle Forms package 
 	 ("\\.rpp$" . pls-mode) ;; Oracle Reports package
 	 ("\\.sf$" . pls-mode)  ;; Stored function 
 	 ("\\.sp$" . pls-mode)  ;; Stored procedure 
 	 ("\\.spb$" . pls-mode) ;; Stored package body
 	 ("\\.spp$" . pls-mode) ;; Stored package specand body
 	 ("\\.sps$" . pls-mode) ;; Stored package specification
 	 ("\\.sql$" . pls-mode) ;; SQL script
 	 ) auto-mode-alist))
