(define-clhs-page :defreadtable
  (:style :macro-definition)
  (:syntax "defreadtable" "defined-readtable-name" "[[options]]" => "readtable")
  (:syntax
   "options ::= (:use readtable-name*)+ |"      (:nl)
   "            (:macro-char char function)* |" (:nl)
   "            (:dispatch-macro-char disp-char sub-char  function)*")
  (:arguments
   ("defined-readtable-name" . "a" (:glossary string-designator))
   ("readtable-name"         . "a" (:link :named-readtable-designator))
   ("char"                   . "a" (:glossary character))
   ("disp-char"              . "a" (:glossary character))
   ("sub-char"               . "a" (:glossary character))
   ("function"               . "a" (:glossary function-designator) "or" (:amb nil))
   ("readtable"              . "a" (:type readtable)))
  (:description
   #"`defreadtable' creates a <:type readtable> as specified by `options' and returns
     the <:type readtable>. If `defined-readtable-name' already refers to an existing
     <:type readtable>, this <:type readtable> is modified instead of creating a new one.

     The `options' are as follows:     
    "
   
   (:dl (:dt (:pre ":use")
	     (:dd #"The <:type readtable \"readtables\"> denoted by the arguments to <:pre \":use\">
                    are merged into one <:type readtable> from left to right. The process of merging
                    is not commutative; reader macros in later entries will overwrite earlier ones.
                    Notice that there must always be at least one <:pre \":use\"> clause given."))
	
	(:dt (:pre ":macro-char")
	     (:dd #"The two arguments to <:pre \":macro-char\"> are processed as if they were
                    passed to <:function set-macro-character> relatively to the current state
                    of the <:type readtable> being defined."))
	
	(:dt (:pre ":dispatch-macro-char")
	     (:dd #"The three arguments to <:pre \":dispatch-macro-char\"> are processed as if
                    they were passed to <:function set-dispatch-macro-character> relatively to
                    the current state of the <:type readtable> being defined.")))

   #"The `options' are processed in the following order: At first, all <:pre \":use\"> clauses
     are processed in the order they appear. Then the remaining clauses are processed in the
     order they appear.

     That is that the following

     <:code \"(defreadtable :foo 
                (:use :standard)
                (:macro-char ch fn1)
                (:use :bar)
                (:dispatch-macro-char dispch subch fn2))\">

     is equivalent to

     <:code \"(defreadtable :foo
                (:use :standard)
                (:use :bar)
                (:macro-char ch fn1)
                (:dispatch-macro-char dispch subch fn2))\">
    ")
  (:affected-by (:paragraph "Existing " (:type readtable "readtables")))
  (:exceptions
   #"An error is signalled if no <:pre \":use\"> clause was provided.

     An error is also signalled if a `readtable-name' refers to a non-existing
     <:type readtable>.")
  (:see-also
   (:link :register-readtable) (:link :in-readtable))
  (:notes
   #"The following

    <:code \"(defreadtable :foo 
               (:use :standard)
               (:use :bar :quux :otto)
               (:use :baz))\">
   
    is equivalent to

    <:code \"(defreadtable :foo (:use :standard :bar :quux :otto :baz))\"

    "))