merged
authorwenzelm
Wed Dec 16 17:30:30 2015 +0100 (2015-12-16)
changeset 6185532a530a5c54c
parent 61849 f8741f200f91
parent 61854 38b049cd3aad
child 61856 4b1b85f38944
child 61862 e2a9e46ac0fb
merged
     1.1 --- a/src/Doc/Eisbach/Manual.thy	Tue Dec 15 14:41:47 2015 +0000
     1.2 +++ b/src/Doc/Eisbach/Manual.thy	Wed Dec 16 17:30:30 2015 +0100
     1.3 @@ -931,7 +931,7 @@
     1.4  
     1.5      attribute_setup get_split_rule =
     1.6        \<open>Args.term >> (fn t =>
     1.7 -        Thm.rule_attribute (fn context => fn _ =>
     1.8 +        Thm.rule_attribute [] (fn context => fn _ =>
     1.9            (case get_split_rule (Context.proof_of context) t of
    1.10              SOME thm => thm
    1.11            | NONE => Drule.dummy_thm)))\<close>
     2.1 --- a/src/Doc/Implementation/Eq.thy	Tue Dec 15 14:41:47 2015 +0000
     2.2 +++ b/src/Doc/Implementation/Eq.thy	Wed Dec 16 17:30:30 2015 +0100
     2.3 @@ -6,52 +6,52 @@
     2.4  
     2.5  chapter \<open>Equational reasoning\<close>
     2.6  
     2.7 -text \<open>Equality is one of the most fundamental concepts of
     2.8 -  mathematics.  The Isabelle/Pure logic (\chref{ch:logic}) provides a
     2.9 -  builtin relation \<open>\<equiv> :: \<alpha> \<Rightarrow> \<alpha> \<Rightarrow> prop\<close> that expresses equality
    2.10 -  of arbitrary terms (or propositions) at the framework level, as
    2.11 -  expressed by certain basic inference rules (\secref{sec:eq-rules}).
    2.12 +text \<open>
    2.13 +  Equality is one of the most fundamental concepts of mathematics. The
    2.14 +  Isabelle/Pure logic (\chref{ch:logic}) provides a builtin relation \<open>\<equiv> :: \<alpha> \<Rightarrow>
    2.15 +  \<alpha> \<Rightarrow> prop\<close> that expresses equality of arbitrary terms (or propositions) at
    2.16 +  the framework level, as expressed by certain basic inference rules
    2.17 +  (\secref{sec:eq-rules}).
    2.18  
    2.19 -  Equational reasoning means to replace equals by equals, using
    2.20 -  reflexivity and transitivity to form chains of replacement steps,
    2.21 -  and congruence rules to access sub-structures.  Conversions
    2.22 -  (\secref{sec:conv}) provide a convenient framework to compose basic
    2.23 -  equational steps to build specific equational reasoning tools.
    2.24 +  Equational reasoning means to replace equals by equals, using reflexivity
    2.25 +  and transitivity to form chains of replacement steps, and congruence rules
    2.26 +  to access sub-structures. Conversions (\secref{sec:conv}) provide a
    2.27 +  convenient framework to compose basic equational steps to build specific
    2.28 +  equational reasoning tools.
    2.29  
    2.30 -  Higher-order matching is able to provide suitable instantiations for
    2.31 -  giving equality rules, which leads to the versatile concept of
    2.32 -  \<open>\<lambda>\<close>-term rewriting (\secref{sec:rewriting}).  Internally
    2.33 -  this is based on the general-purpose Simplifier engine of Isabelle,
    2.34 -  which is more specific and more efficient than plain conversions.
    2.35 +  Higher-order matching is able to provide suitable instantiations for giving
    2.36 +  equality rules, which leads to the versatile concept of \<open>\<lambda>\<close>-term rewriting
    2.37 +  (\secref{sec:rewriting}). Internally this is based on the general-purpose
    2.38 +  Simplifier engine of Isabelle, which is more specific and more efficient
    2.39 +  than plain conversions.
    2.40  
    2.41 -  Object-logics usually introduce specific notions of equality or
    2.42 -  equivalence, and relate it with the Pure equality.  This enables to
    2.43 -  re-use the Pure tools for equational reasoning for particular
    2.44 -  object-logic connectives as well.
    2.45 +  Object-logics usually introduce specific notions of equality or equivalence,
    2.46 +  and relate it with the Pure equality. This enables to re-use the Pure tools
    2.47 +  for equational reasoning for particular object-logic connectives as well.
    2.48  \<close>
    2.49  
    2.50  
    2.51  section \<open>Basic equality rules \label{sec:eq-rules}\<close>
    2.52  
    2.53 -text \<open>Isabelle/Pure uses \<open>\<equiv>\<close> for equality of arbitrary
    2.54 -  terms, which includes equivalence of propositions of the logical
    2.55 -  framework.  The conceptual axiomatization of the constant \<open>\<equiv>
    2.56 -  :: \<alpha> \<Rightarrow> \<alpha> \<Rightarrow> prop\<close> is given in \figref{fig:pure-equality}.  The
    2.57 -  inference kernel presents slightly different equality rules, which
    2.58 -  may be understood as derived rules from this minimal axiomatization.
    2.59 -  The Pure theory also provides some theorems that express the same
    2.60 -  reasoning schemes as theorems that can be composed like object-level
    2.61 +text \<open>
    2.62 +  Isabelle/Pure uses \<open>\<equiv>\<close> for equality of arbitrary terms, which includes
    2.63 +  equivalence of propositions of the logical framework. The conceptual
    2.64 +  axiomatization of the constant \<open>\<equiv> :: \<alpha> \<Rightarrow> \<alpha> \<Rightarrow> prop\<close> is given in
    2.65 +  \figref{fig:pure-equality}. The inference kernel presents slightly different
    2.66 +  equality rules, which may be understood as derived rules from this minimal
    2.67 +  axiomatization. The Pure theory also provides some theorems that express the
    2.68 +  same reasoning schemes as theorems that can be composed like object-level
    2.69    rules as explained in \secref{sec:obj-rules}.
    2.70  
    2.71 -  For example, @{ML Thm.symmetric} as Pure inference is an ML function
    2.72 -  that maps a theorem \<open>th\<close> stating \<open>t \<equiv> u\<close> to one
    2.73 -  stating \<open>u \<equiv> t\<close>.  In contrast, @{thm [source]
    2.74 -  Pure.symmetric} as Pure theorem expresses the same reasoning in
    2.75 -  declarative form.  If used like \<open>th [THEN Pure.symmetric]\<close>
    2.76 -  in Isar source notation, it achieves a similar effect as the ML
    2.77 -  inference function, although the rule attribute @{attribute THEN} or
    2.78 -  ML operator @{ML "op RS"} involve the full machinery of higher-order
    2.79 -  unification (modulo \<open>\<beta>\<eta>\<close>-conversion) and lifting of \<open>\<And>/\<Longrightarrow>\<close> contexts.\<close>
    2.80 +  For example, @{ML Thm.symmetric} as Pure inference is an ML function that
    2.81 +  maps a theorem \<open>th\<close> stating \<open>t \<equiv> u\<close> to one stating \<open>u \<equiv> t\<close>. In contrast,
    2.82 +  @{thm [source] Pure.symmetric} as Pure theorem expresses the same reasoning
    2.83 +  in declarative form. If used like \<open>th [THEN Pure.symmetric]\<close> in Isar source
    2.84 +  notation, it achieves a similar effect as the ML inference function,
    2.85 +  although the rule attribute @{attribute THEN} or ML operator @{ML "op RS"}
    2.86 +  involve the full machinery of higher-order unification (modulo
    2.87 +  \<open>\<beta>\<eta>\<close>-conversion) and lifting of \<open>\<And>/\<Longrightarrow>\<close> contexts.
    2.88 +\<close>
    2.89  
    2.90  text %mlref \<open>
    2.91    \begin{mldecls}
    2.92 @@ -64,11 +64,11 @@
    2.93    @{index_ML Thm.equal_elim: "thm -> thm -> thm"} \\
    2.94    \end{mldecls}
    2.95  
    2.96 -  See also @{file "~~/src/Pure/thm.ML" } for further description of
    2.97 -  these inference rules, and a few more for primitive \<open>\<beta>\<close> and
    2.98 -  \<open>\<eta>\<close> conversions.  Note that \<open>\<alpha>\<close> conversion is
    2.99 -  implicit due to the representation of terms with de-Bruijn indices
   2.100 -  (\secref{sec:terms}).\<close>
   2.101 +  See also @{file "~~/src/Pure/thm.ML" } for further description of these
   2.102 +  inference rules, and a few more for primitive \<open>\<beta>\<close> and \<open>\<eta>\<close> conversions. Note
   2.103 +  that \<open>\<alpha>\<close> conversion is implicit due to the representation of terms with
   2.104 +  de-Bruijn indices (\secref{sec:terms}).
   2.105 +\<close>
   2.106  
   2.107  
   2.108  section \<open>Conversions \label{sec:conv}\<close>
   2.109 @@ -76,19 +76,19 @@
   2.110  text \<open>
   2.111    %FIXME
   2.112  
   2.113 -  The classic article that introduces the concept of conversion (for
   2.114 -  Cambridge LCF) is @{cite "paulson:1983"}.
   2.115 +  The classic article that introduces the concept of conversion (for Cambridge
   2.116 +  LCF) is @{cite "paulson:1983"}.
   2.117  \<close>
   2.118  
   2.119  
   2.120  section \<open>Rewriting \label{sec:rewriting}\<close>
   2.121  
   2.122 -text \<open>Rewriting normalizes a given term (theorem or goal) by
   2.123 -  replacing instances of given equalities \<open>t \<equiv> u\<close> in subterms.
   2.124 -  Rewriting continues until no rewrites are applicable to any subterm.
   2.125 -  This may be used to unfold simple definitions of the form \<open>f
   2.126 -  x\<^sub>1 \<dots> x\<^sub>n \<equiv> u\<close>, but is slightly more general than that.
   2.127 -\<close>
   2.128 +text \<open>
   2.129 +  Rewriting normalizes a given term (theorem or goal) by replacing instances
   2.130 +  of given equalities \<open>t \<equiv> u\<close> in subterms. Rewriting continues until no
   2.131 +  rewrites are applicable to any subterm. This may be used to unfold simple
   2.132 +  definitions of the form \<open>f x\<^sub>1 \<dots> x\<^sub>n \<equiv> u\<close>, but is slightly more general than
   2.133 +  that. \<close>
   2.134  
   2.135  text %mlref \<open>
   2.136    \begin{mldecls}
   2.137 @@ -99,24 +99,24 @@
   2.138    @{index_ML fold_goals_tac: "Proof.context -> thm list -> tactic"} \\
   2.139    \end{mldecls}
   2.140  
   2.141 -  \<^descr> @{ML rewrite_rule}~\<open>ctxt rules thm\<close> rewrites the whole
   2.142 -  theorem by the given rules.
   2.143 +  \<^descr> @{ML rewrite_rule}~\<open>ctxt rules thm\<close> rewrites the whole theorem by the
   2.144 +  given rules.
   2.145  
   2.146 -  \<^descr> @{ML rewrite_goals_rule}~\<open>ctxt rules thm\<close> rewrites the
   2.147 -  outer premises of the given theorem.  Interpreting the same as a
   2.148 -  goal state (\secref{sec:tactical-goals}) it means to rewrite all
   2.149 -  subgoals (in the same manner as @{ML rewrite_goals_tac}).
   2.150 +  \<^descr> @{ML rewrite_goals_rule}~\<open>ctxt rules thm\<close> rewrites the outer premises of
   2.151 +  the given theorem. Interpreting the same as a goal state
   2.152 +  (\secref{sec:tactical-goals}) it means to rewrite all subgoals (in the same
   2.153 +  manner as @{ML rewrite_goals_tac}).
   2.154  
   2.155 -  \<^descr> @{ML rewrite_goal_tac}~\<open>ctxt rules i\<close> rewrites subgoal
   2.156 -  \<open>i\<close> by the given rewrite rules.
   2.157 +  \<^descr> @{ML rewrite_goal_tac}~\<open>ctxt rules i\<close> rewrites subgoal \<open>i\<close> by the given
   2.158 +  rewrite rules.
   2.159  
   2.160 -  \<^descr> @{ML rewrite_goals_tac}~\<open>ctxt rules\<close> rewrites all subgoals
   2.161 -  by the given rewrite rules.
   2.162 +  \<^descr> @{ML rewrite_goals_tac}~\<open>ctxt rules\<close> rewrites all subgoals by the given
   2.163 +  rewrite rules.
   2.164  
   2.165 -  \<^descr> @{ML fold_goals_tac}~\<open>ctxt rules\<close> essentially uses @{ML
   2.166 -  rewrite_goals_tac} with the symmetric form of each member of \<open>rules\<close>, re-ordered to fold longer expression first.  This supports
   2.167 -  to idea to fold primitive definitions that appear in expended form
   2.168 -  in the proof state.
   2.169 +  \<^descr> @{ML fold_goals_tac}~\<open>ctxt rules\<close> essentially uses @{ML rewrite_goals_tac}
   2.170 +  with the symmetric form of each member of \<open>rules\<close>, re-ordered to fold longer
   2.171 +  expression first. This supports to idea to fold primitive definitions that
   2.172 +  appear in expended form in the proof state.
   2.173  \<close>
   2.174  
   2.175  end
     3.1 --- a/src/Doc/Implementation/Integration.thy	Tue Dec 15 14:41:47 2015 +0000
     3.2 +++ b/src/Doc/Implementation/Integration.thy	Wed Dec 16 17:30:30 2015 +0100
     3.3 @@ -9,8 +9,8 @@
     3.4  section \<open>Isar toplevel \label{sec:isar-toplevel}\<close>
     3.5  
     3.6  text \<open>
     3.7 -  The Isar \<^emph>\<open>toplevel state\<close> represents the outermost configuration that
     3.8 -  is transformed by a sequence of transitions (commands) within a theory body.
     3.9 +  The Isar \<^emph>\<open>toplevel state\<close> represents the outermost configuration that is
    3.10 +  transformed by a sequence of transitions (commands) within a theory body.
    3.11    This is a pure value with pure functions acting on it in a timeless and
    3.12    stateless manner. Historically, the sequence of transitions was wrapped up
    3.13    as sequential command loop, such that commands are applied one-by-one. In
    3.14 @@ -23,15 +23,16 @@
    3.15  subsection \<open>Toplevel state\<close>
    3.16  
    3.17  text \<open>
    3.18 -  The toplevel state is a disjoint sum of empty \<open>toplevel\<close>, or \<open>theory\<close>, or \<open>proof\<close>. The initial toplevel is empty; a theory is
    3.19 -  commenced by a @{command theory} header; within a theory we may use theory
    3.20 -  commands such as @{command definition}, or state a @{command theorem} to be
    3.21 -  proven. A proof state accepts a rich collection of Isar proof commands for
    3.22 -  structured proof composition, or unstructured proof scripts. When the proof
    3.23 -  is concluded we get back to the (local) theory, which is then updated by
    3.24 -  defining the resulting fact. Further theory declarations or theorem
    3.25 -  statements with proofs may follow, until we eventually conclude the theory
    3.26 -  development by issuing @{command end} to get back to the empty toplevel.
    3.27 +  The toplevel state is a disjoint sum of empty \<open>toplevel\<close>, or \<open>theory\<close>, or
    3.28 +  \<open>proof\<close>. The initial toplevel is empty; a theory is commenced by a @{command
    3.29 +  theory} header; within a theory we may use theory commands such as @{command
    3.30 +  definition}, or state a @{command theorem} to be proven. A proof state
    3.31 +  accepts a rich collection of Isar proof commands for structured proof
    3.32 +  composition, or unstructured proof scripts. When the proof is concluded we
    3.33 +  get back to the (local) theory, which is then updated by defining the
    3.34 +  resulting fact. Further theory declarations or theorem statements with
    3.35 +  proofs may follow, until we eventually conclude the theory development by
    3.36 +  issuing @{command end} to get back to the empty toplevel.
    3.37  \<close>
    3.38  
    3.39  text %mlref \<open>
    3.40 @@ -43,23 +44,21 @@
    3.41    @{index_ML Toplevel.proof_of: "Toplevel.state -> Proof.state"} \\
    3.42    \end{mldecls}
    3.43  
    3.44 -  \<^descr> Type @{ML_type Toplevel.state} represents Isar toplevel
    3.45 -  states, which are normally manipulated through the concept of
    3.46 -  toplevel transitions only (\secref{sec:toplevel-transition}).
    3.47 +  \<^descr> Type @{ML_type Toplevel.state} represents Isar toplevel states, which are
    3.48 +  normally manipulated through the concept of toplevel transitions only
    3.49 +  (\secref{sec:toplevel-transition}).
    3.50  
    3.51 -  \<^descr> @{ML Toplevel.UNDEF} is raised for undefined toplevel
    3.52 -  operations.  Many operations work only partially for certain cases,
    3.53 -  since @{ML_type Toplevel.state} is a sum type.
    3.54 +  \<^descr> @{ML Toplevel.UNDEF} is raised for undefined toplevel operations. Many
    3.55 +  operations work only partially for certain cases, since @{ML_type
    3.56 +  Toplevel.state} is a sum type.
    3.57  
    3.58 -  \<^descr> @{ML Toplevel.is_toplevel}~\<open>state\<close> checks for an empty
    3.59 -  toplevel state.
    3.60 +  \<^descr> @{ML Toplevel.is_toplevel}~\<open>state\<close> checks for an empty toplevel state.
    3.61  
    3.62 -  \<^descr> @{ML Toplevel.theory_of}~\<open>state\<close> selects the
    3.63 -  background theory of \<open>state\<close>, it raises @{ML Toplevel.UNDEF}
    3.64 -  for an empty toplevel state.
    3.65 +  \<^descr> @{ML Toplevel.theory_of}~\<open>state\<close> selects the background theory of \<open>state\<close>,
    3.66 +  it raises @{ML Toplevel.UNDEF} for an empty toplevel state.
    3.67  
    3.68 -  \<^descr> @{ML Toplevel.proof_of}~\<open>state\<close> selects the Isar proof
    3.69 -  state if available, otherwise it raises an error.
    3.70 +  \<^descr> @{ML Toplevel.proof_of}~\<open>state\<close> selects the Isar proof state if available,
    3.71 +  otherwise it raises an error.
    3.72  \<close>
    3.73  
    3.74  text %mlantiq \<open>
    3.75 @@ -67,11 +66,11 @@
    3.76    @{ML_antiquotation_def "Isar.state"} & : & \<open>ML_antiquotation\<close> \\
    3.77    \end{matharray}
    3.78  
    3.79 -  \<^descr> \<open>@{Isar.state}\<close> refers to Isar toplevel state at that
    3.80 -  point --- as abstract value.
    3.81 +  \<^descr> \<open>@{Isar.state}\<close> refers to Isar toplevel state at that point --- as
    3.82 +  abstract value.
    3.83  
    3.84 -  This only works for diagnostic ML commands, such as @{command
    3.85 -  ML_val} or @{command ML_command}.
    3.86 +  This only works for diagnostic ML commands, such as @{command ML_val} or
    3.87 +  @{command ML_command}.
    3.88  \<close>
    3.89  
    3.90  
    3.91 @@ -82,12 +81,11 @@
    3.92    state, with additional information for diagnostics and error reporting:
    3.93    there are fields for command name, source position, and other meta-data.
    3.94  
    3.95 -  The operational part is represented as the sequential union of a
    3.96 -  list of partial functions, which are tried in turn until the first
    3.97 -  one succeeds.  This acts like an outer case-expression for various
    3.98 -  alternative state transitions.  For example, \isakeyword{qed} works
    3.99 -  differently for a local proofs vs.\ the global ending of an outermost
   3.100 -  proof.
   3.101 +  The operational part is represented as the sequential union of a list of
   3.102 +  partial functions, which are tried in turn until the first one succeeds.
   3.103 +  This acts like an outer case-expression for various alternative state
   3.104 +  transitions. For example, \isakeyword{qed} works differently for a local
   3.105 +  proofs vs.\ the global ending of an outermost proof.
   3.106  
   3.107    Transitions are composed via transition transformers. Internally, Isar
   3.108    commands are put together from an empty transition extended by name and
   3.109 @@ -112,34 +110,32 @@
   3.110    Toplevel.transition -> Toplevel.transition"} \\
   3.111    \end{mldecls}
   3.112  
   3.113 -  \<^descr> @{ML Toplevel.keep}~\<open>tr\<close> adjoins a diagnostic
   3.114 -  function.
   3.115 +  \<^descr> @{ML Toplevel.keep}~\<open>tr\<close> adjoins a diagnostic function.
   3.116 +
   3.117 +  \<^descr> @{ML Toplevel.theory}~\<open>tr\<close> adjoins a theory transformer.
   3.118  
   3.119 -  \<^descr> @{ML Toplevel.theory}~\<open>tr\<close> adjoins a theory
   3.120 -  transformer.
   3.121 +  \<^descr> @{ML Toplevel.theory_to_proof}~\<open>tr\<close> adjoins a global goal function, which
   3.122 +  turns a theory into a proof state. The theory may be changed before entering
   3.123 +  the proof; the generic Isar goal setup includes an \<^verbatim>\<open>after_qed\<close> argument
   3.124 +  that specifies how to apply the proven result to the enclosing context, when
   3.125 +  the proof is finished.
   3.126  
   3.127 -  \<^descr> @{ML Toplevel.theory_to_proof}~\<open>tr\<close> adjoins a global
   3.128 -  goal function, which turns a theory into a proof state.  The theory
   3.129 -  may be changed before entering the proof; the generic Isar goal
   3.130 -  setup includes an \<^verbatim>\<open>after_qed\<close> argument that specifies how to
   3.131 -  apply the proven result to the enclosing context, when the proof
   3.132 -  is finished.
   3.133 +  \<^descr> @{ML Toplevel.proof}~\<open>tr\<close> adjoins a deterministic proof command, with a
   3.134 +  singleton result.
   3.135  
   3.136 -  \<^descr> @{ML Toplevel.proof}~\<open>tr\<close> adjoins a deterministic
   3.137 -  proof command, with a singleton result.
   3.138 +  \<^descr> @{ML Toplevel.proofs}~\<open>tr\<close> adjoins a general proof command, with zero or
   3.139 +  more result states (represented as a lazy list).
   3.140  
   3.141 -  \<^descr> @{ML Toplevel.proofs}~\<open>tr\<close> adjoins a general proof
   3.142 -  command, with zero or more result states (represented as a lazy
   3.143 -  list).
   3.144 -
   3.145 -  \<^descr> @{ML Toplevel.end_proof}~\<open>tr\<close> adjoins a concluding
   3.146 -  proof command, that returns the resulting theory, after applying the
   3.147 -  resulting facts to the target context.
   3.148 +  \<^descr> @{ML Toplevel.end_proof}~\<open>tr\<close> adjoins a concluding proof command, that
   3.149 +  returns the resulting theory, after applying the resulting facts to the
   3.150 +  target context.
   3.151  \<close>
   3.152  
   3.153 -text %mlex \<open>The file @{"file" "~~/src/HOL/ex/Commands.thy"} shows some example
   3.154 -Isar command definitions, with the all-important theory header declarations
   3.155 -for outer syntax keywords.\<close>
   3.156 +text %mlex \<open>
   3.157 +  The file @{"file" "~~/src/HOL/ex/Commands.thy"} shows some example Isar
   3.158 +  command definitions, with the all-important theory header declarations for
   3.159 +  outer syntax keywords.
   3.160 +\<close>
   3.161  
   3.162  
   3.163  section \<open>Theory loader database\<close>
   3.164 @@ -149,8 +145,8 @@
   3.165    a collection of theories as a directed acyclic graph. A theory may refer to
   3.166    other theories as @{keyword "imports"}, or to auxiliary files via special
   3.167    \<^emph>\<open>load commands\<close> (e.g.\ @{command ML_file}). For each theory, the base
   3.168 -  directory of its own theory file is called \<^emph>\<open>master directory\<close>: this is
   3.169 -  used as the relative location to refer to other files from that theory.
   3.170 +  directory of its own theory file is called \<^emph>\<open>master directory\<close>: this is used
   3.171 +  as the relative location to refer to other files from that theory.
   3.172  \<close>
   3.173  
   3.174  text %mlref \<open>
   3.175 @@ -162,28 +158,27 @@
   3.176    @{index_ML Thy_Info.register_thy: "theory -> unit"} \\
   3.177    \end{mldecls}
   3.178  
   3.179 -  \<^descr> @{ML use_thy}~\<open>A\<close> ensures that theory \<open>A\<close> is fully
   3.180 -  up-to-date wrt.\ the external file store; outdated ancestors are reloaded on
   3.181 -  demand.
   3.182 +  \<^descr> @{ML use_thy}~\<open>A\<close> ensures that theory \<open>A\<close> is fully up-to-date wrt.\ the
   3.183 +  external file store; outdated ancestors are reloaded on demand.
   3.184  
   3.185 -  \<^descr> @{ML use_thys} is similar to @{ML use_thy}, but handles several
   3.186 -  theories simultaneously. Thus it acts like processing the import header of a
   3.187 -  theory, without performing the merge of the result. By loading a whole
   3.188 -  sub-graph of theories, the intrinsic parallelism can be exploited by the
   3.189 -  system to speedup loading.
   3.190 +  \<^descr> @{ML use_thys} is similar to @{ML use_thy}, but handles several theories
   3.191 +  simultaneously. Thus it acts like processing the import header of a theory,
   3.192 +  without performing the merge of the result. By loading a whole sub-graph of
   3.193 +  theories, the intrinsic parallelism can be exploited by the system to
   3.194 +  speedup loading.
   3.195  
   3.196    This variant is used by default in @{tool build} @{cite "isabelle-system"}.
   3.197  
   3.198 -  \<^descr> @{ML Thy_Info.get_theory}~\<open>A\<close> retrieves the theory value
   3.199 -  presently associated with name \<open>A\<close>. Note that the result might be
   3.200 -  outdated wrt.\ the file-system content.
   3.201 +  \<^descr> @{ML Thy_Info.get_theory}~\<open>A\<close> retrieves the theory value presently
   3.202 +  associated with name \<open>A\<close>. Note that the result might be outdated wrt.\ the
   3.203 +  file-system content.
   3.204  
   3.205 -  \<^descr> @{ML Thy_Info.remove_thy}~\<open>A\<close> deletes theory \<open>A\<close> and all
   3.206 -  descendants from the theory database.
   3.207 +  \<^descr> @{ML Thy_Info.remove_thy}~\<open>A\<close> deletes theory \<open>A\<close> and all descendants from
   3.208 +  the theory database.
   3.209  
   3.210 -  \<^descr> @{ML Thy_Info.register_thy}~\<open>text thy\<close> registers an existing
   3.211 -  theory value with the theory loader database and updates source version
   3.212 -  information according to the file store.
   3.213 +  \<^descr> @{ML Thy_Info.register_thy}~\<open>text thy\<close> registers an existing theory value
   3.214 +  with the theory loader database and updates source version information
   3.215 +  according to the file store.
   3.216  \<close>
   3.217  
   3.218  end
     4.1 --- a/src/Doc/Implementation/Isar.thy	Tue Dec 15 14:41:47 2015 +0000
     4.2 +++ b/src/Doc/Implementation/Isar.thy	Wed Dec 16 17:30:30 2015 +0100
     4.3 @@ -6,60 +6,57 @@
     4.4  
     4.5  chapter \<open>Isar language elements\<close>
     4.6  
     4.7 -text \<open>The Isar proof language (see also
     4.8 -  @{cite \<open>\S2\<close> "isabelle-isar-ref"}) consists of three main categories of
     4.9 -  language elements:
    4.10 +text \<open>
    4.11 +  The Isar proof language (see also @{cite \<open>\S2\<close> "isabelle-isar-ref"})
    4.12 +  consists of three main categories of language elements:
    4.13  
    4.14 -  \<^enum> Proof \<^emph>\<open>commands\<close> define the primary language of
    4.15 -  transactions of the underlying Isar/VM interpreter.  Typical
    4.16 -  examples are @{command "fix"}, @{command "assume"}, @{command
    4.17 -  "show"}, @{command "proof"}, and @{command "qed"}.
    4.18 +  \<^enum> Proof \<^emph>\<open>commands\<close> define the primary language of transactions of the
    4.19 +  underlying Isar/VM interpreter. Typical examples are @{command "fix"},
    4.20 +  @{command "assume"}, @{command "show"}, @{command "proof"}, and @{command
    4.21 +  "qed"}.
    4.22  
    4.23 -  Composing proof commands according to the rules of the Isar/VM leads
    4.24 -  to expressions of structured proof text, such that both the machine
    4.25 -  and the human reader can give it a meaning as formal reasoning.
    4.26 +  Composing proof commands according to the rules of the Isar/VM leads to
    4.27 +  expressions of structured proof text, such that both the machine and the
    4.28 +  human reader can give it a meaning as formal reasoning.
    4.29  
    4.30 -  \<^enum> Proof \<^emph>\<open>methods\<close> define a secondary language of mixed
    4.31 -  forward-backward refinement steps involving facts and goals.
    4.32 -  Typical examples are @{method rule}, @{method unfold}, and @{method
    4.33 -  simp}.
    4.34 +  \<^enum> Proof \<^emph>\<open>methods\<close> define a secondary language of mixed forward-backward
    4.35 +  refinement steps involving facts and goals. Typical examples are @{method
    4.36 +  rule}, @{method unfold}, and @{method simp}.
    4.37  
    4.38 -  Methods can occur in certain well-defined parts of the Isar proof
    4.39 -  language, say as arguments to @{command "proof"}, @{command "qed"},
    4.40 -  or @{command "by"}.
    4.41 +  Methods can occur in certain well-defined parts of the Isar proof language,
    4.42 +  say as arguments to @{command "proof"}, @{command "qed"}, or @{command
    4.43 +  "by"}.
    4.44  
    4.45 -  \<^enum> \<^emph>\<open>Attributes\<close> define a tertiary language of small
    4.46 -  annotations to theorems being defined or referenced.  Attributes can
    4.47 -  modify both the context and the theorem.
    4.48 +  \<^enum> \<^emph>\<open>Attributes\<close> define a tertiary language of small annotations to theorems
    4.49 +  being defined or referenced. Attributes can modify both the context and the
    4.50 +  theorem.
    4.51  
    4.52 -  Typical examples are @{attribute intro} (which affects the context),
    4.53 -  and @{attribute symmetric} (which affects the theorem).
    4.54 +  Typical examples are @{attribute intro} (which affects the context), and
    4.55 +  @{attribute symmetric} (which affects the theorem).
    4.56  \<close>
    4.57  
    4.58  
    4.59  section \<open>Proof commands\<close>
    4.60  
    4.61 -text \<open>A \<^emph>\<open>proof command\<close> is state transition of the Isar/VM
    4.62 -  proof interpreter.
    4.63 +text \<open>
    4.64 +  A \<^emph>\<open>proof command\<close> is state transition of the Isar/VM proof interpreter.
    4.65  
    4.66 -  In principle, Isar proof commands could be defined in user-space as
    4.67 -  well.  The system is built like that in the first place: one part of
    4.68 -  the commands are primitive, the other part is defined as derived
    4.69 -  elements.  Adding to the genuine structured proof language requires
    4.70 -  profound understanding of the Isar/VM machinery, though, so this is
    4.71 -  beyond the scope of this manual.
    4.72 +  In principle, Isar proof commands could be defined in user-space as well.
    4.73 +  The system is built like that in the first place: one part of the commands
    4.74 +  are primitive, the other part is defined as derived elements. Adding to the
    4.75 +  genuine structured proof language requires profound understanding of the
    4.76 +  Isar/VM machinery, though, so this is beyond the scope of this manual.
    4.77  
    4.78 -  What can be done realistically is to define some diagnostic commands
    4.79 -  that inspect the general state of the Isar/VM, and report some
    4.80 -  feedback to the user.  Typically this involves checking of the
    4.81 -  linguistic \<^emph>\<open>mode\<close> of a proof state, or peeking at the pending
    4.82 -  goals (if available).
    4.83 +  What can be done realistically is to define some diagnostic commands that
    4.84 +  inspect the general state of the Isar/VM, and report some feedback to the
    4.85 +  user. Typically this involves checking of the linguistic \<^emph>\<open>mode\<close> of a proof
    4.86 +  state, or peeking at the pending goals (if available).
    4.87  
    4.88 -  Another common application is to define a toplevel command that
    4.89 -  poses a problem to the user as Isar proof state and processes the
    4.90 -  final result relatively to the context.  Thus a proof can be
    4.91 -  incorporated into the context of some user-space tool, without
    4.92 -  modifying the Isar proof language itself.\<close>
    4.93 +  Another common application is to define a toplevel command that poses a
    4.94 +  problem to the user as Isar proof state and processes the final result
    4.95 +  relatively to the context. Thus a proof can be incorporated into the context
    4.96 +  of some user-space tool, without modifying the Isar proof language itself.
    4.97 +\<close>
    4.98  
    4.99  text %mlref \<open>
   4.100    \begin{mldecls}
   4.101 @@ -77,61 +74,56 @@
   4.102    (term * term list) list list -> Proof.context -> Proof.state"} \\
   4.103    \end{mldecls}
   4.104  
   4.105 -  \<^descr> Type @{ML_type Proof.state} represents Isar proof states.
   4.106 -  This is a block-structured configuration with proof context,
   4.107 -  linguistic mode, and optional goal.  The latter consists of goal
   4.108 -  context, goal facts (``\<open>using\<close>''), and tactical goal state
   4.109 -  (see \secref{sec:tactical-goals}).
   4.110 +  \<^descr> Type @{ML_type Proof.state} represents Isar proof states. This is a
   4.111 +  block-structured configuration with proof context, linguistic mode, and
   4.112 +  optional goal. The latter consists of goal context, goal facts
   4.113 +  (``\<open>using\<close>''), and tactical goal state (see \secref{sec:tactical-goals}).
   4.114  
   4.115 -  The general idea is that the facts shall contribute to the
   4.116 -  refinement of some parts of the tactical goal --- how exactly is
   4.117 -  defined by the proof method that is applied in that situation.
   4.118 +  The general idea is that the facts shall contribute to the refinement of
   4.119 +  some parts of the tactical goal --- how exactly is defined by the proof
   4.120 +  method that is applied in that situation.
   4.121  
   4.122    \<^descr> @{ML Proof.assert_forward}, @{ML Proof.assert_chain}, @{ML
   4.123 -  Proof.assert_backward} are partial identity functions that fail
   4.124 -  unless a certain linguistic mode is active, namely ``\<open>proof(state)\<close>'', ``\<open>proof(chain)\<close>'', ``\<open>proof(prove)\<close>'', respectively (using the terminology of
   4.125 -  @{cite "isabelle-isar-ref"}).
   4.126 +  Proof.assert_backward} are partial identity functions that fail unless a
   4.127 +  certain linguistic mode is active, namely ``\<open>proof(state)\<close>'',
   4.128 +  ``\<open>proof(chain)\<close>'', ``\<open>proof(prove)\<close>'', respectively (using the terminology
   4.129 +  of @{cite "isabelle-isar-ref"}).
   4.130  
   4.131 -  It is advisable study the implementations of existing proof commands
   4.132 -  for suitable modes to be asserted.
   4.133 +  It is advisable study the implementations of existing proof commands for
   4.134 +  suitable modes to be asserted.
   4.135  
   4.136 -  \<^descr> @{ML Proof.simple_goal}~\<open>state\<close> returns the structured
   4.137 -  Isar goal (if available) in the form seen by ``simple'' methods
   4.138 -  (like @{method simp} or @{method blast}).  The Isar goal facts are
   4.139 -  already inserted as premises into the subgoals, which are presented
   4.140 -  individually as in @{ML Proof.goal}.
   4.141 +  \<^descr> @{ML Proof.simple_goal}~\<open>state\<close> returns the structured Isar goal (if
   4.142 +  available) in the form seen by ``simple'' methods (like @{method simp} or
   4.143 +  @{method blast}). The Isar goal facts are already inserted as premises into
   4.144 +  the subgoals, which are presented individually as in @{ML Proof.goal}.
   4.145  
   4.146 -  \<^descr> @{ML Proof.goal}~\<open>state\<close> returns the structured Isar
   4.147 -  goal (if available) in the form seen by regular methods (like
   4.148 -  @{method rule}).  The auxiliary internal encoding of Pure
   4.149 -  conjunctions is split into individual subgoals as usual.
   4.150 +  \<^descr> @{ML Proof.goal}~\<open>state\<close> returns the structured Isar goal (if available)
   4.151 +  in the form seen by regular methods (like @{method rule}). The auxiliary
   4.152 +  internal encoding of Pure conjunctions is split into individual subgoals as
   4.153 +  usual.
   4.154  
   4.155 -  \<^descr> @{ML Proof.raw_goal}~\<open>state\<close> returns the structured
   4.156 -  Isar goal (if available) in the raw internal form seen by ``raw''
   4.157 -  methods (like @{method induct}).  This form is rarely appropriate
   4.158 -  for diagnostic tools; @{ML Proof.simple_goal} or @{ML Proof.goal}
   4.159 -  should be used in most situations.
   4.160 +  \<^descr> @{ML Proof.raw_goal}~\<open>state\<close> returns the structured Isar goal (if
   4.161 +  available) in the raw internal form seen by ``raw'' methods (like @{method
   4.162 +  induct}). This form is rarely appropriate for diagnostic tools; @{ML
   4.163 +  Proof.simple_goal} or @{ML Proof.goal} should be used in most situations.
   4.164  
   4.165 -  \<^descr> @{ML Proof.theorem}~\<open>before_qed after_qed statement ctxt\<close>
   4.166 -  initializes a toplevel Isar proof state within a given context.
   4.167 +  \<^descr> @{ML Proof.theorem}~\<open>before_qed after_qed statement ctxt\<close> initializes a
   4.168 +  toplevel Isar proof state within a given context.
   4.169  
   4.170 -  The optional \<open>before_qed\<close> method is applied at the end of
   4.171 -  the proof, just before extracting the result (this feature is rarely
   4.172 -  used).
   4.173 +  The optional \<open>before_qed\<close> method is applied at the end of the proof, just
   4.174 +  before extracting the result (this feature is rarely used).
   4.175  
   4.176 -  The \<open>after_qed\<close> continuation receives the extracted result
   4.177 -  in order to apply it to the final context in a suitable way (e.g.\
   4.178 -  storing named facts).  Note that at this generic level the target
   4.179 -  context is specified as @{ML_type Proof.context}, but the usual
   4.180 -  wrapping of toplevel proofs into command transactions will provide a
   4.181 -  @{ML_type local_theory} here (\chref{ch:local-theory}).  This
   4.182 -  affects the way how results are stored.
   4.183 +  The \<open>after_qed\<close> continuation receives the extracted result in order to apply
   4.184 +  it to the final context in a suitable way (e.g.\ storing named facts). Note
   4.185 +  that at this generic level the target context is specified as @{ML_type
   4.186 +  Proof.context}, but the usual wrapping of toplevel proofs into command
   4.187 +  transactions will provide a @{ML_type local_theory} here
   4.188 +  (\chref{ch:local-theory}). This affects the way how results are stored.
   4.189  
   4.190 -  The \<open>statement\<close> is given as a nested list of terms, each
   4.191 -  associated with optional @{keyword "is"} patterns as usual in the
   4.192 -  Isar source language.  The original nested list structure over terms
   4.193 -  is turned into one over theorems when \<open>after_qed\<close> is
   4.194 -  invoked.
   4.195 +  The \<open>statement\<close> is given as a nested list of terms, each associated with
   4.196 +  optional @{keyword "is"} patterns as usual in the Isar source language. The
   4.197 +  original nested list structure over terms is turned into one over theorems
   4.198 +  when \<open>after_qed\<close> is invoked.
   4.199  \<close>
   4.200  
   4.201  
   4.202 @@ -140,15 +132,16 @@
   4.203    @{ML_antiquotation_def "Isar.goal"} & : & \<open>ML_antiquotation\<close> \\
   4.204    \end{matharray}
   4.205  
   4.206 -  \<^descr> \<open>@{Isar.goal}\<close> refers to the regular goal state (if
   4.207 -  available) of the current proof state managed by the Isar toplevel
   4.208 -  --- as abstract value.
   4.209 +  \<^descr> \<open>@{Isar.goal}\<close> refers to the regular goal state (if available) of the
   4.210 +  current proof state managed by the Isar toplevel --- as abstract value.
   4.211  
   4.212 -  This only works for diagnostic ML commands, such as @{command
   4.213 -  ML_val} or @{command ML_command}.
   4.214 +  This only works for diagnostic ML commands, such as @{command ML_val} or
   4.215 +  @{command ML_command}.
   4.216  \<close>
   4.217  
   4.218 -text %mlex \<open>The following example peeks at a certain goal configuration.\<close>
   4.219 +text %mlex \<open>
   4.220 +  The following example peeks at a certain goal configuration.
   4.221 +\<close>
   4.222  
   4.223  notepad
   4.224  begin
   4.225 @@ -159,8 +152,10 @@
   4.226      sorry
   4.227  end
   4.228  
   4.229 -text \<open>Here we see 3 individual subgoals in the same way as regular
   4.230 -  proof methods would do.\<close>
   4.231 +text \<open>
   4.232 +  Here we see 3 individual subgoals in the same way as regular proof methods
   4.233 +  would do.
   4.234 +\<close>
   4.235  
   4.236  
   4.237  section \<open>Proof methods\<close>
   4.238 @@ -172,42 +167,38 @@
   4.239    normal circumstances, the goal context remains unchanged, but it is also
   4.240    possible to declare named extensions of the proof context (\<^emph>\<open>cases\<close>).
   4.241  
   4.242 -  This means a proof method is like a structurally enhanced tactic
   4.243 -  (cf.\ \secref{sec:tactics}).  The well-formedness conditions for
   4.244 -  tactics need to hold for methods accordingly, with the following
   4.245 -  additions.
   4.246 +  This means a proof method is like a structurally enhanced tactic (cf.\
   4.247 +  \secref{sec:tactics}). The well-formedness conditions for tactics need to
   4.248 +  hold for methods accordingly, with the following additions.
   4.249  
   4.250 -  \<^item> Goal addressing is further limited either to operate
   4.251 -  uniformly on \<^emph>\<open>all\<close> subgoals, or specifically on the
   4.252 -  \<^emph>\<open>first\<close> subgoal.
   4.253 +  \<^item> Goal addressing is further limited either to operate uniformly on \<^emph>\<open>all\<close>
   4.254 +  subgoals, or specifically on the \<^emph>\<open>first\<close> subgoal.
   4.255  
   4.256 -  Exception: old-style tactic emulations that are embedded into the
   4.257 -  method space, e.g.\ @{method rule_tac}.
   4.258 +  Exception: old-style tactic emulations that are embedded into the method
   4.259 +  space, e.g.\ @{method rule_tac}.
   4.260  
   4.261 -  \<^item> A non-trivial method always needs to make progress: an
   4.262 -  identical follow-up goal state has to be avoided.\<^footnote>\<open>This
   4.263 -  enables the user to write method expressions like \<open>meth\<^sup>+\<close>
   4.264 -  without looping, while the trivial do-nothing case can be recovered
   4.265 -  via \<open>meth\<^sup>?\<close>.\<close>
   4.266 +  \<^item> A non-trivial method always needs to make progress: an identical follow-up
   4.267 +  goal state has to be avoided.\<^footnote>\<open>This enables the user to write method
   4.268 +  expressions like \<open>meth\<^sup>+\<close> without looping, while the trivial do-nothing case
   4.269 +  can be recovered via \<open>meth\<^sup>?\<close>.\<close>
   4.270  
   4.271 -  Exception: trivial stuttering steps, such as ``@{method -}'' or
   4.272 -  @{method succeed}.
   4.273 +  Exception: trivial stuttering steps, such as ``@{method -}'' or @{method
   4.274 +  succeed}.
   4.275  
   4.276 -  \<^item> Goal facts passed to the method must not be ignored.  If there
   4.277 -  is no sensible use of facts outside the goal state, facts should be
   4.278 -  inserted into the subgoals that are addressed by the method.
   4.279 +  \<^item> Goal facts passed to the method must not be ignored. If there is no
   4.280 +  sensible use of facts outside the goal state, facts should be inserted into
   4.281 +  the subgoals that are addressed by the method.
   4.282  
   4.283  
   4.284    \<^medskip>
   4.285 -  Syntactically, the language of proof methods appears as
   4.286 -  arguments to Isar commands like @{command "by"} or @{command apply}.
   4.287 -  User-space additions are reasonably easy by plugging suitable
   4.288 -  method-valued parser functions into the framework, using the
   4.289 -  @{command method_setup} command, for example.
   4.290 +  Syntactically, the language of proof methods appears as arguments to Isar
   4.291 +  commands like @{command "by"} or @{command apply}. User-space additions are
   4.292 +  reasonably easy by plugging suitable method-valued parser functions into the
   4.293 +  framework, using the @{command method_setup} command, for example.
   4.294  
   4.295    To get a better idea about the range of possibilities, consider the
   4.296 -  following Isar proof schemes.  This is the general form of
   4.297 -  structured proof text:
   4.298 +  following Isar proof schemes. This is the general form of structured proof
   4.299 +  text:
   4.300  
   4.301    \<^medskip>
   4.302    \begin{tabular}{l}
   4.303 @@ -218,11 +209,12 @@
   4.304    \end{tabular}
   4.305    \<^medskip>
   4.306  
   4.307 -  The goal configuration consists of \<open>facts\<^sub>1\<close> and
   4.308 -  \<open>facts\<^sub>2\<close> appended in that order, and various \<open>props\<close> being claimed.  The \<open>initial_method\<close> is invoked
   4.309 -  with facts and goals together and refines the problem to something
   4.310 -  that is handled recursively in the proof \<open>body\<close>.  The \<open>terminal_method\<close> has another chance to finish any remaining
   4.311 -  subgoals, but it does not see the facts of the initial step.
   4.312 +  The goal configuration consists of \<open>facts\<^sub>1\<close> and \<open>facts\<^sub>2\<close> appended in that
   4.313 +  order, and various \<open>props\<close> being claimed. The \<open>initial_method\<close> is invoked
   4.314 +  with facts and goals together and refines the problem to something that is
   4.315 +  handled recursively in the proof \<open>body\<close>. The \<open>terminal_method\<close> has another
   4.316 +  chance to finish any remaining subgoals, but it does not see the facts of
   4.317 +  the initial step.
   4.318  
   4.319    \<^medskip>
   4.320    This pattern illustrates unstructured proof scripts:
   4.321 @@ -237,51 +229,48 @@
   4.322    \end{tabular}
   4.323    \<^medskip>
   4.324  
   4.325 -  The \<open>method\<^sub>1\<close> operates on the original claim while
   4.326 -  using \<open>facts\<^sub>1\<close>.  Since the @{command apply} command
   4.327 -  structurally resets the facts, the \<open>method\<^sub>2\<close> will
   4.328 -  operate on the remaining goal state without facts.  The \<open>method\<^sub>3\<close> will see again a collection of \<open>facts\<^sub>3\<close> that has been inserted into the script explicitly.
   4.329 +  The \<open>method\<^sub>1\<close> operates on the original claim while using \<open>facts\<^sub>1\<close>. Since
   4.330 +  the @{command apply} command structurally resets the facts, the \<open>method\<^sub>2\<close>
   4.331 +  will operate on the remaining goal state without facts. The \<open>method\<^sub>3\<close> will
   4.332 +  see again a collection of \<open>facts\<^sub>3\<close> that has been inserted into the script
   4.333 +  explicitly.
   4.334  
   4.335    \<^medskip>
   4.336 -  Empirically, any Isar proof method can be categorized as
   4.337 -  follows.
   4.338 +  Empirically, any Isar proof method can be categorized as follows.
   4.339  
   4.340 -  \<^enum> \<^emph>\<open>Special method with cases\<close> with named context additions
   4.341 -  associated with the follow-up goal state.
   4.342 +    \<^enum> \<^emph>\<open>Special method with cases\<close> with named context additions associated
   4.343 +    with the follow-up goal state.
   4.344  
   4.345 -  Example: @{method "induct"}, which is also a ``raw'' method since it
   4.346 -  operates on the internal representation of simultaneous claims as
   4.347 -  Pure conjunction (\secref{sec:logic-aux}), instead of separate
   4.348 -  subgoals (\secref{sec:tactical-goals}).
   4.349 +    Example: @{method "induct"}, which is also a ``raw'' method since it
   4.350 +    operates on the internal representation of simultaneous claims as Pure
   4.351 +    conjunction (\secref{sec:logic-aux}), instead of separate subgoals
   4.352 +    (\secref{sec:tactical-goals}).
   4.353  
   4.354 -  \<^enum> \<^emph>\<open>Structured method\<close> with strong emphasis on facts outside
   4.355 -  the goal state.
   4.356 +    \<^enum> \<^emph>\<open>Structured method\<close> with strong emphasis on facts outside the goal
   4.357 +    state.
   4.358  
   4.359 -  Example: @{method "rule"}, which captures the key ideas behind
   4.360 -  structured reasoning in Isar in its purest form.
   4.361 +    Example: @{method "rule"}, which captures the key ideas behind structured
   4.362 +    reasoning in Isar in its purest form.
   4.363  
   4.364 -  \<^enum> \<^emph>\<open>Simple method\<close> with weaker emphasis on facts, which are
   4.365 -  inserted into subgoals to emulate old-style tactical ``premises''.
   4.366 -
   4.367 -  Examples: @{method "simp"}, @{method "blast"}, @{method "auto"}.
   4.368 +    \<^enum> \<^emph>\<open>Simple method\<close> with weaker emphasis on facts, which are inserted into
   4.369 +    subgoals to emulate old-style tactical ``premises''.
   4.370  
   4.371 -  \<^enum> \<^emph>\<open>Old-style tactic emulation\<close> with detailed numeric goal
   4.372 -  addressing and explicit references to entities of the internal goal
   4.373 -  state (which are otherwise invisible from proper Isar proof text).
   4.374 -  The naming convention \<open>foo_tac\<close> makes this special
   4.375 -  non-standard status clear.
   4.376 +    Examples: @{method "simp"}, @{method "blast"}, @{method "auto"}.
   4.377  
   4.378 -  Example: @{method "rule_tac"}.
   4.379 +    \<^enum> \<^emph>\<open>Old-style tactic emulation\<close> with detailed numeric goal addressing and
   4.380 +    explicit references to entities of the internal goal state (which are
   4.381 +    otherwise invisible from proper Isar proof text). The naming convention
   4.382 +    \<open>foo_tac\<close> makes this special non-standard status clear.
   4.383  
   4.384 +    Example: @{method "rule_tac"}.
   4.385  
   4.386    When implementing proof methods, it is advisable to study existing
   4.387 -  implementations carefully and imitate the typical ``boiler plate''
   4.388 -  for context-sensitive parsing and further combinators to wrap-up
   4.389 -  tactic expressions as methods.\<^footnote>\<open>Aliases or abbreviations of
   4.390 -  the standard method combinators should be avoided.  Note that from
   4.391 -  Isabelle99 until Isabelle2009 the system did provide various odd
   4.392 -  combinations of method syntax wrappers that made applications more
   4.393 -  complicated than necessary.\<close>
   4.394 +  implementations carefully and imitate the typical ``boiler plate'' for
   4.395 +  context-sensitive parsing and further combinators to wrap-up tactic
   4.396 +  expressions as methods.\<^footnote>\<open>Aliases or abbreviations of the standard method
   4.397 +  combinators should be avoided. Note that from Isabelle99 until Isabelle2009
   4.398 +  the system did provide various odd combinations of method syntax wrappers
   4.399 +  that made applications more complicated than necessary.\<close>
   4.400  \<close>
   4.401  
   4.402  text %mlref \<open>
   4.403 @@ -296,8 +285,7 @@
   4.404    string -> theory -> theory"} \\
   4.405    \end{mldecls}
   4.406  
   4.407 -  \<^descr> Type @{ML_type Proof.method} represents proof methods as
   4.408 -  abstract type.
   4.409 +  \<^descr> Type @{ML_type Proof.method} represents proof methods as abstract type.
   4.410  
   4.411    \<^descr> @{ML CONTEXT_METHOD}~\<open>(fn facts => context_tactic)\<close> wraps \<open>context_tactic\<close>
   4.412    depending on goal facts as a general proof method that may change the proof
   4.413 @@ -305,36 +293,36 @@
   4.414    Proof_Context.update_cases}, which is wrapped up as combinator @{index_ML
   4.415    CONTEXT_CASES} for convenience.
   4.416  
   4.417 -  \<^descr> @{ML METHOD}~\<open>(fn facts => tactic)\<close> wraps \<open>tactic\<close> depending on goal facts as regular proof method; the goal
   4.418 -  context is passed via method syntax.
   4.419 +  \<^descr> @{ML METHOD}~\<open>(fn facts => tactic)\<close> wraps \<open>tactic\<close> depending on goal facts
   4.420 +  as regular proof method; the goal context is passed via method syntax.
   4.421  
   4.422 -  \<^descr> @{ML SIMPLE_METHOD}~\<open>tactic\<close> wraps a tactic that
   4.423 -  addresses all subgoals uniformly as simple proof method.  Goal facts
   4.424 -  are already inserted into all subgoals before \<open>tactic\<close> is
   4.425 -  applied.
   4.426 +  \<^descr> @{ML SIMPLE_METHOD}~\<open>tactic\<close> wraps a tactic that addresses all subgoals
   4.427 +  uniformly as simple proof method. Goal facts are already inserted into all
   4.428 +  subgoals before \<open>tactic\<close> is applied.
   4.429  
   4.430 -  \<^descr> @{ML SIMPLE_METHOD'}~\<open>tactic\<close> wraps a tactic that
   4.431 -  addresses a specific subgoal as simple proof method that operates on
   4.432 -  subgoal 1.  Goal facts are inserted into the subgoal then the \<open>tactic\<close> is applied.
   4.433 +  \<^descr> @{ML SIMPLE_METHOD'}~\<open>tactic\<close> wraps a tactic that addresses a specific
   4.434 +  subgoal as simple proof method that operates on subgoal 1. Goal facts are
   4.435 +  inserted into the subgoal then the \<open>tactic\<close> is applied.
   4.436  
   4.437 -  \<^descr> @{ML Method.insert_tac}~\<open>ctxt facts i\<close> inserts \<open>facts\<close> into subgoal \<open>i\<close>.  This is convenient to reproduce
   4.438 -  part of the @{ML SIMPLE_METHOD} or @{ML SIMPLE_METHOD'} wrapping
   4.439 -  within regular @{ML METHOD}, for example.
   4.440 +  \<^descr> @{ML Method.insert_tac}~\<open>ctxt facts i\<close> inserts \<open>facts\<close> into subgoal \<open>i\<close>.
   4.441 +  This is convenient to reproduce part of the @{ML SIMPLE_METHOD} or @{ML
   4.442 +  SIMPLE_METHOD'} wrapping within regular @{ML METHOD}, for example.
   4.443  
   4.444 -  \<^descr> @{ML Method.setup}~\<open>name parser description\<close> provides
   4.445 -  the functionality of the Isar command @{command method_setup} as ML
   4.446 -  function.
   4.447 +  \<^descr> @{ML Method.setup}~\<open>name parser description\<close> provides the functionality of
   4.448 +  the Isar command @{command method_setup} as ML function.
   4.449  \<close>
   4.450  
   4.451 -text %mlex \<open>See also @{command method_setup} in
   4.452 -  @{cite "isabelle-isar-ref"} which includes some abstract examples.
   4.453 +text %mlex \<open>
   4.454 +  See also @{command method_setup} in @{cite "isabelle-isar-ref"} which
   4.455 +  includes some abstract examples.
   4.456  
   4.457    \<^medskip>
   4.458 -  The following toy examples illustrate how the goal facts
   4.459 -  and state are passed to proof methods.  The predefined proof method
   4.460 -  called ``@{method tactic}'' wraps ML source of type @{ML_type
   4.461 -  tactic} (abstracted over @{ML_text facts}).  This allows immediate
   4.462 -  experimentation without parsing of concrete syntax.\<close>
   4.463 +  The following toy examples illustrate how the goal facts and state are
   4.464 +  passed to proof methods. The predefined proof method called ``@{method
   4.465 +  tactic}'' wraps ML source of type @{ML_type tactic} (abstracted over
   4.466 +  @{ML_text facts}). This allows immediate experimentation without parsing of
   4.467 +  concrete syntax.
   4.468 +\<close>
   4.469  
   4.470  notepad
   4.471  begin
   4.472 @@ -357,8 +345,9 @@
   4.473  
   4.474  text \<open>
   4.475    \<^medskip>
   4.476 -  The next example implements a method that simplifies
   4.477 -  the first subgoal by rewrite rules that are given as arguments.\<close>
   4.478 +  The next example implements a method that simplifies the first subgoal by
   4.479 +  rewrite rules that are given as arguments.
   4.480 +\<close>
   4.481  
   4.482  method_setup my_simp =
   4.483    \<open>Attrib.thms >> (fn thms => fn ctxt =>
   4.484 @@ -367,21 +356,21 @@
   4.485          (put_simpset HOL_basic_ss ctxt addsimps thms) i)))\<close>
   4.486    "rewrite subgoal by given rules"
   4.487  
   4.488 -text \<open>The concrete syntax wrapping of @{command method_setup} always
   4.489 -  passes-through the proof context at the end of parsing, but it is
   4.490 -  not used in this example.
   4.491 +text \<open>
   4.492 +  The concrete syntax wrapping of @{command method_setup} always
   4.493 +  passes-through the proof context at the end of parsing, but it is not used
   4.494 +  in this example.
   4.495  
   4.496 -  The @{ML Attrib.thms} parser produces a list of theorems from the
   4.497 -  usual Isar syntax involving attribute expressions etc.\ (syntax
   4.498 -  category @{syntax thmrefs}) @{cite "isabelle-isar-ref"}.  The resulting
   4.499 -  @{ML_text thms} are added to @{ML HOL_basic_ss} which already
   4.500 -  contains the basic Simplifier setup for HOL.
   4.501 +  The @{ML Attrib.thms} parser produces a list of theorems from the usual Isar
   4.502 +  syntax involving attribute expressions etc.\ (syntax category @{syntax
   4.503 +  thmrefs}) @{cite "isabelle-isar-ref"}. The resulting @{ML_text thms} are
   4.504 +  added to @{ML HOL_basic_ss} which already contains the basic Simplifier
   4.505 +  setup for HOL.
   4.506  
   4.507 -  The tactic @{ML asm_full_simp_tac} is the one that is also used in
   4.508 -  method @{method simp} by default.  The extra wrapping by the @{ML
   4.509 -  CHANGED} tactical ensures progress of simplification: identical goal
   4.510 -  states are filtered out explicitly to make the raw tactic conform to
   4.511 -  standard Isar method behaviour.
   4.512 +  The tactic @{ML asm_full_simp_tac} is the one that is also used in method
   4.513 +  @{method simp} by default. The extra wrapping by the @{ML CHANGED} tactical
   4.514 +  ensures progress of simplification: identical goal states are filtered out
   4.515 +  explicitly to make the raw tactic conform to standard Isar method behaviour.
   4.516  
   4.517    \<^medskip>
   4.518    Method @{method my_simp} can be used in Isar proofs like this:
   4.519 @@ -395,8 +384,9 @@
   4.520    have "a = c" by (my_simp a b)
   4.521  end
   4.522  
   4.523 -text \<open>Here is a similar method that operates on all subgoals,
   4.524 -  instead of just the first one.\<close>
   4.525 +text \<open>
   4.526 +  Here is a similar method that operates on all subgoals, instead of just the
   4.527 +  first one.\<close>
   4.528  
   4.529  method_setup my_simp_all =
   4.530    \<open>Attrib.thms >> (fn thms => fn ctxt =>
   4.531 @@ -416,15 +406,18 @@
   4.532  
   4.533  text \<open>
   4.534    \<^medskip>
   4.535 -  Apart from explicit arguments, common proof methods
   4.536 -  typically work with a default configuration provided by the context. As a
   4.537 -  shortcut to rule management we use a cheap solution via the @{command
   4.538 -  named_theorems} command to declare a dynamic fact in the context.\<close>
   4.539 +  Apart from explicit arguments, common proof methods typically work with a
   4.540 +  default configuration provided by the context. As a shortcut to rule
   4.541 +  management we use a cheap solution via the @{command named_theorems} command
   4.542 +  to declare a dynamic fact in the context.
   4.543 +\<close>
   4.544  
   4.545  named_theorems my_simp
   4.546  
   4.547 -text \<open>The proof method is now defined as before, but we append the
   4.548 -  explicit arguments and the rules from the context.\<close>
   4.549 +text \<open>
   4.550 +  The proof method is now defined as before, but we append the explicit
   4.551 +  arguments and the rules from the context.
   4.552 +\<close>
   4.553  
   4.554  method_setup my_simp' =
   4.555    \<open>Attrib.thms >> (fn thms => fn ctxt =>
   4.556 @@ -440,8 +433,7 @@
   4.557  
   4.558  text \<open>
   4.559    \<^medskip>
   4.560 -  Method @{method my_simp'} can be used in Isar proofs
   4.561 -  like this:
   4.562 +  Method @{method my_simp'} can be used in Isar proofs like this:
   4.563  \<close>
   4.564  
   4.565  notepad
   4.566 @@ -454,84 +446,88 @@
   4.567  
   4.568  text \<open>
   4.569    \<^medskip>
   4.570 -  The @{method my_simp} variants defined above are
   4.571 -  ``simple'' methods, i.e.\ the goal facts are merely inserted as goal
   4.572 -  premises by the @{ML SIMPLE_METHOD'} or @{ML SIMPLE_METHOD} wrapper.
   4.573 -  For proof methods that are similar to the standard collection of
   4.574 -  @{method simp}, @{method blast}, @{method fast}, @{method auto}
   4.575 -  there is little more that can be done.
   4.576 +  The @{method my_simp} variants defined above are ``simple'' methods, i.e.\
   4.577 +  the goal facts are merely inserted as goal premises by the @{ML
   4.578 +  SIMPLE_METHOD'} or @{ML SIMPLE_METHOD} wrapper. For proof methods that are
   4.579 +  similar to the standard collection of @{method simp}, @{method blast},
   4.580 +  @{method fast}, @{method auto} there is little more that can be done.
   4.581  
   4.582 -  Note that using the primary goal facts in the same manner as the
   4.583 -  method arguments obtained via concrete syntax or the context does
   4.584 -  not meet the requirement of ``strong emphasis on facts'' of regular
   4.585 -  proof methods, because rewrite rules as used above can be easily
   4.586 -  ignored.  A proof text ``@{command using}~\<open>foo\<close>~@{command
   4.587 -  "by"}~\<open>my_simp\<close>'' where \<open>foo\<close> is not used would
   4.588 -  deceive the reader.
   4.589 +  Note that using the primary goal facts in the same manner as the method
   4.590 +  arguments obtained via concrete syntax or the context does not meet the
   4.591 +  requirement of ``strong emphasis on facts'' of regular proof methods,
   4.592 +  because rewrite rules as used above can be easily ignored. A proof text
   4.593 +  ``@{command using}~\<open>foo\<close>~@{command "by"}~\<open>my_simp\<close>'' where \<open>foo\<close> is not used
   4.594 +  would deceive the reader.
   4.595  
   4.596    \<^medskip>
   4.597 -  The technical treatment of rules from the context requires
   4.598 -  further attention.  Above we rebuild a fresh @{ML_type simpset} from
   4.599 -  the arguments and \<^emph>\<open>all\<close> rules retrieved from the context on
   4.600 -  every invocation of the method.  This does not scale to really large
   4.601 -  collections of rules, which easily emerges in the context of a big
   4.602 -  theory library, for example.
   4.603 +  The technical treatment of rules from the context requires further
   4.604 +  attention. Above we rebuild a fresh @{ML_type simpset} from the arguments
   4.605 +  and \<^emph>\<open>all\<close> rules retrieved from the context on every invocation of the
   4.606 +  method. This does not scale to really large collections of rules, which
   4.607 +  easily emerges in the context of a big theory library, for example.
   4.608  
   4.609    This is an inherent limitation of the simplistic rule management via
   4.610 -  @{command named_theorems}, because it lacks tool-specific
   4.611 -  storage and retrieval.  More realistic applications require
   4.612 -  efficient index-structures that organize theorems in a customized
   4.613 -  manner, such as a discrimination net that is indexed by the
   4.614 -  left-hand sides of rewrite rules.  For variations on the Simplifier,
   4.615 -  re-use of the existing type @{ML_type simpset} is adequate, but
   4.616 -  scalability would require it be maintained statically within the
   4.617 -  context data, not dynamically on each tool invocation.\<close>
   4.618 +  @{command named_theorems}, because it lacks tool-specific storage and
   4.619 +  retrieval. More realistic applications require efficient index-structures
   4.620 +  that organize theorems in a customized manner, such as a discrimination net
   4.621 +  that is indexed by the left-hand sides of rewrite rules. For variations on
   4.622 +  the Simplifier, re-use of the existing type @{ML_type simpset} is adequate,
   4.623 +  but scalability would require it be maintained statically within the context
   4.624 +  data, not dynamically on each tool invocation.
   4.625 +\<close>
   4.626  
   4.627  
   4.628  section \<open>Attributes \label{sec:attributes}\<close>
   4.629  
   4.630 -text \<open>An \<^emph>\<open>attribute\<close> is a function \<open>context \<times> thm \<rightarrow>
   4.631 -  context \<times> thm\<close>, which means both a (generic) context and a theorem
   4.632 -  can be modified simultaneously.  In practice this mixed form is very
   4.633 -  rare, instead attributes are presented either as \<^emph>\<open>declaration
   4.634 -  attribute:\<close> \<open>thm \<rightarrow> context \<rightarrow> context\<close> or \<^emph>\<open>rule
   4.635 +text \<open>
   4.636 +  An \<^emph>\<open>attribute\<close> is a function \<open>context \<times> thm \<rightarrow> context \<times> thm\<close>, which means
   4.637 +  both a (generic) context and a theorem can be modified simultaneously. In
   4.638 +  practice this mixed form is very rare, instead attributes are presented
   4.639 +  either as \<^emph>\<open>declaration attribute:\<close> \<open>thm \<rightarrow> context \<rightarrow> context\<close> or \<^emph>\<open>rule
   4.640    attribute:\<close> \<open>context \<rightarrow> thm \<rightarrow> thm\<close>.
   4.641  
   4.642 -  Attributes can have additional arguments via concrete syntax.  There
   4.643 -  is a collection of context-sensitive parsers for various logical
   4.644 -  entities (types, terms, theorems).  These already take care of
   4.645 -  applying morphisms to the arguments when attribute expressions are
   4.646 -  moved into a different context (see also \secref{sec:morphisms}).
   4.647 +  Attributes can have additional arguments via concrete syntax. There is a
   4.648 +  collection of context-sensitive parsers for various logical entities (types,
   4.649 +  terms, theorems). These already take care of applying morphisms to the
   4.650 +  arguments when attribute expressions are moved into a different context (see
   4.651 +  also \secref{sec:morphisms}).
   4.652  
   4.653 -  When implementing declaration attributes, it is important to operate
   4.654 -  exactly on the variant of the generic context that is provided by
   4.655 -  the system, which is either global theory context or local proof
   4.656 -  context.  In particular, the background theory of a local context
   4.657 -  must not be modified in this situation!\<close>
   4.658 +  When implementing declaration attributes, it is important to operate exactly
   4.659 +  on the variant of the generic context that is provided by the system, which
   4.660 +  is either global theory context or local proof context. In particular, the
   4.661 +  background theory of a local context must not be modified in this
   4.662 +  situation!
   4.663 +\<close>
   4.664  
   4.665  text %mlref \<open>
   4.666    \begin{mldecls}
   4.667    @{index_ML_type attribute} \\
   4.668 -  @{index_ML Thm.rule_attribute: "(Context.generic -> thm -> thm) -> attribute"} \\
   4.669 +  @{index_ML Thm.rule_attribute: "thm list ->
   4.670 +  (Context.generic -> thm -> thm) -> attribute"} \\
   4.671    @{index_ML Thm.declaration_attribute: "
   4.672    (thm -> Context.generic -> Context.generic) -> attribute"} \\
   4.673    @{index_ML Attrib.setup: "binding -> attribute context_parser ->
   4.674    string -> theory -> theory"} \\
   4.675    \end{mldecls}
   4.676  
   4.677 -  \<^descr> Type @{ML_type attribute} represents attributes as concrete
   4.678 -  type alias.
   4.679 +  \<^descr> Type @{ML_type attribute} represents attributes as concrete type alias.
   4.680  
   4.681 -  \<^descr> @{ML Thm.rule_attribute}~\<open>(fn context => rule)\<close> wraps
   4.682 -  a context-dependent rule (mapping on @{ML_type thm}) as attribute.
   4.683 +  \<^descr> @{ML Thm.rule_attribute}~\<open>thms (fn context => rule)\<close> wraps a
   4.684 +  context-dependent rule (mapping on @{ML_type thm}) as attribute.
   4.685 +
   4.686 +  The \<open>thms\<close> are additional parameters: when forming an abstract closure, the
   4.687 +  system may provide dummy facts that are propagated according to strict
   4.688 +  evaluation discipline. In that case, \<open>rule\<close> is bypassed.
   4.689  
   4.690 -  \<^descr> @{ML Thm.declaration_attribute}~\<open>(fn thm => decl)\<close>
   4.691 -  wraps a theorem-dependent declaration (mapping on @{ML_type
   4.692 -  Context.generic}) as attribute.
   4.693 +  \<^descr> @{ML Thm.declaration_attribute}~\<open>(fn thm => decl)\<close> wraps a
   4.694 +  theorem-dependent declaration (mapping on @{ML_type Context.generic}) as
   4.695 +  attribute.
   4.696  
   4.697 -  \<^descr> @{ML Attrib.setup}~\<open>name parser description\<close> provides
   4.698 -  the functionality of the Isar command @{command attribute_setup} as
   4.699 -  ML function.
   4.700 +  When forming an abstract closure, the system may provide a dummy fact as
   4.701 +  \<open>thm\<close>. In that case, \<open>decl\<close> is bypassed.
   4.702 +
   4.703 +  \<^descr> @{ML Attrib.setup}~\<open>name parser description\<close> provides the functionality of
   4.704 +  the Isar command @{command attribute_setup} as ML function.
   4.705  \<close>
   4.706  
   4.707  text %mlantiq \<open>
   4.708 @@ -543,15 +539,16 @@
   4.709    @@{ML_antiquotation attributes} attributes
   4.710    \<close>}
   4.711  
   4.712 -  \<^descr> \<open>@{attributes [\<dots>]}\<close> embeds attribute source
   4.713 -  representation into the ML text, which is particularly useful with
   4.714 -  declarations like @{ML Local_Theory.note}.  Attribute names are
   4.715 -  internalized at compile time, but the source is unevaluated.  This
   4.716 -  means attributes with formal arguments (types, terms, theorems) may
   4.717 -  be subject to odd effects of dynamic scoping!
   4.718 +  \<^descr> \<open>@{attributes [\<dots>]}\<close> embeds attribute source representation into the ML
   4.719 +  text, which is particularly useful with declarations like @{ML
   4.720 +  Local_Theory.note}. Attribute names are internalized at compile time, but
   4.721 +  the source is unevaluated. This means attributes with formal arguments
   4.722 +  (types, terms, theorems) may be subject to odd effects of dynamic scoping!
   4.723  \<close>
   4.724  
   4.725 -text %mlex \<open>See also @{command attribute_setup} in
   4.726 -  @{cite "isabelle-isar-ref"} which includes some abstract examples.\<close>
   4.727 +text %mlex \<open>
   4.728 +  See also @{command attribute_setup} in @{cite "isabelle-isar-ref"} which
   4.729 +  includes some abstract examples.
   4.730 +\<close>
   4.731  
   4.732  end
     5.1 --- a/src/Doc/Implementation/Local_Theory.thy	Tue Dec 15 14:41:47 2015 +0000
     5.2 +++ b/src/Doc/Implementation/Local_Theory.thy	Wed Dec 16 17:30:30 2015 +0100
     5.3 @@ -7,49 +7,45 @@
     5.4  chapter \<open>Local theory specifications \label{ch:local-theory}\<close>
     5.5  
     5.6  text \<open>
     5.7 -  A \<^emph>\<open>local theory\<close> combines aspects of both theory and proof
     5.8 -  context (cf.\ \secref{sec:context}), such that definitional
     5.9 -  specifications may be given relatively to parameters and
    5.10 -  assumptions.  A local theory is represented as a regular proof
    5.11 -  context, augmented by administrative data about the \<^emph>\<open>target
    5.12 +  A \<^emph>\<open>local theory\<close> combines aspects of both theory and proof context (cf.\
    5.13 +  \secref{sec:context}), such that definitional specifications may be given
    5.14 +  relatively to parameters and assumptions. A local theory is represented as a
    5.15 +  regular proof context, augmented by administrative data about the \<^emph>\<open>target
    5.16    context\<close>.
    5.17  
    5.18 -  The target is usually derived from the background theory by adding
    5.19 -  local \<open>\<FIX>\<close> and \<open>\<ASSUME>\<close> elements, plus
    5.20 -  suitable modifications of non-logical context data (e.g.\ a special
    5.21 -  type-checking discipline).  Once initialized, the target is ready to
    5.22 -  absorb definitional primitives: \<open>\<DEFINE>\<close> for terms and
    5.23 -  \<open>\<NOTE>\<close> for theorems.  Such definitions may get
    5.24 -  transformed in a target-specific way, but the programming interface
    5.25 -  hides such details.
    5.26 +  The target is usually derived from the background theory by adding local
    5.27 +  \<open>\<FIX>\<close> and \<open>\<ASSUME>\<close> elements, plus suitable modifications of
    5.28 +  non-logical context data (e.g.\ a special type-checking discipline). Once
    5.29 +  initialized, the target is ready to absorb definitional primitives:
    5.30 +  \<open>\<DEFINE>\<close> for terms and \<open>\<NOTE>\<close> for theorems. Such definitions may get
    5.31 +  transformed in a target-specific way, but the programming interface hides
    5.32 +  such details.
    5.33  
    5.34    Isabelle/Pure provides target mechanisms for locales, type-classes,
    5.35 -  type-class instantiations, and general overloading.  In principle,
    5.36 -  users can implement new targets as well, but this rather arcane
    5.37 -  discipline is beyond the scope of this manual.  In contrast,
    5.38 -  implementing derived definitional packages to be used within a local
    5.39 -  theory context is quite easy: the interfaces are even simpler and
    5.40 -  more abstract than the underlying primitives for raw theories.
    5.41 +  type-class instantiations, and general overloading. In principle, users can
    5.42 +  implement new targets as well, but this rather arcane discipline is beyond
    5.43 +  the scope of this manual. In contrast, implementing derived definitional
    5.44 +  packages to be used within a local theory context is quite easy: the
    5.45 +  interfaces are even simpler and more abstract than the underlying primitives
    5.46 +  for raw theories.
    5.47  
    5.48 -  Many definitional packages for local theories are available in
    5.49 -  Isabelle.  Although a few old packages only work for global
    5.50 -  theories, the standard way of implementing definitional packages in
    5.51 -  Isabelle is via the local theory interface.
    5.52 +  Many definitional packages for local theories are available in Isabelle.
    5.53 +  Although a few old packages only work for global theories, the standard way
    5.54 +  of implementing definitional packages in Isabelle is via the local theory
    5.55 +  interface.
    5.56  \<close>
    5.57  
    5.58  
    5.59  section \<open>Definitional elements\<close>
    5.60  
    5.61  text \<open>
    5.62 -  There are separate elements \<open>\<DEFINE> c \<equiv> t\<close> for terms, and
    5.63 -  \<open>\<NOTE> b = thm\<close> for theorems.  Types are treated
    5.64 -  implicitly, according to Hindley-Milner discipline (cf.\
    5.65 -  \secref{sec:variables}).  These definitional primitives essentially
    5.66 -  act like \<open>let\<close>-bindings within a local context that may
    5.67 -  already contain earlier \<open>let\<close>-bindings and some initial
    5.68 -  \<open>\<lambda>\<close>-bindings.  Thus we gain \<^emph>\<open>dependent definitions\<close>
    5.69 -  that are relative to an initial axiomatic context.  The following
    5.70 -  diagram illustrates this idea of axiomatic elements versus
    5.71 +  There are separate elements \<open>\<DEFINE> c \<equiv> t\<close> for terms, and \<open>\<NOTE> b =
    5.72 +  thm\<close> for theorems. Types are treated implicitly, according to Hindley-Milner
    5.73 +  discipline (cf.\ \secref{sec:variables}). These definitional primitives
    5.74 +  essentially act like \<open>let\<close>-bindings within a local context that may already
    5.75 +  contain earlier \<open>let\<close>-bindings and some initial \<open>\<lambda>\<close>-bindings. Thus we gain
    5.76 +  \<^emph>\<open>dependent definitions\<close> that are relative to an initial axiomatic context.
    5.77 +  The following diagram illustrates this idea of axiomatic elements versus
    5.78    definitional elements:
    5.79  
    5.80    \begin{center}
    5.81 @@ -64,34 +60,33 @@
    5.82    \end{tabular}
    5.83    \end{center}
    5.84  
    5.85 -  A user package merely needs to produce suitable \<open>\<DEFINE>\<close>
    5.86 -  and \<open>\<NOTE>\<close> elements according to the application.  For
    5.87 -  example, a package for inductive definitions might first \<open>\<DEFINE>\<close> a certain predicate as some fixed-point construction,
    5.88 -  then \<open>\<NOTE>\<close> a proven result about monotonicity of the
    5.89 +  A user package merely needs to produce suitable \<open>\<DEFINE>\<close> and \<open>\<NOTE>\<close>
    5.90 +  elements according to the application. For example, a package for inductive
    5.91 +  definitions might first \<open>\<DEFINE>\<close> a certain predicate as some fixed-point
    5.92 +  construction, then \<open>\<NOTE>\<close> a proven result about monotonicity of the
    5.93    functor involved here, and then produce further derived concepts via
    5.94    additional \<open>\<DEFINE>\<close> and \<open>\<NOTE>\<close> elements.
    5.95  
    5.96 -  The cumulative sequence of \<open>\<DEFINE>\<close> and \<open>\<NOTE>\<close>
    5.97 -  produced at package runtime is managed by the local theory
    5.98 -  infrastructure by means of an \<^emph>\<open>auxiliary context\<close>.  Thus the
    5.99 -  system holds up the impression of working within a fully abstract
   5.100 -  situation with hypothetical entities: \<open>\<DEFINE> c \<equiv> t\<close>
   5.101 -  always results in a literal fact \<open>\<^BG>c \<equiv> t\<^EN>\<close>, where
   5.102 -  \<open>c\<close> is a fixed variable \<open>c\<close>.  The details about
   5.103 -  global constants, name spaces etc. are handled internally.
   5.104 +  The cumulative sequence of \<open>\<DEFINE>\<close> and \<open>\<NOTE>\<close> produced at package
   5.105 +  runtime is managed by the local theory infrastructure by means of an
   5.106 +  \<^emph>\<open>auxiliary context\<close>. Thus the system holds up the impression of working
   5.107 +  within a fully abstract situation with hypothetical entities: \<open>\<DEFINE> c \<equiv>
   5.108 +  t\<close> always results in a literal fact \<open>\<^BG>c \<equiv> t\<^EN>\<close>, where \<open>c\<close> is a
   5.109 +  fixed variable \<open>c\<close>. The details about global constants, name spaces etc. are
   5.110 +  handled internally.
   5.111  
   5.112 -  So the general structure of a local theory is a sandwich of three
   5.113 -  layers:
   5.114 +  So the general structure of a local theory is a sandwich of three layers:
   5.115  
   5.116    \begin{center}
   5.117    \framebox{\quad auxiliary context \quad\framebox{\quad target context \quad\framebox{\quad background theory\quad}}}
   5.118    \end{center}
   5.119  
   5.120 -  When a definitional package is finished, the auxiliary context is
   5.121 -  reset to the target context.  The target now holds definitions for
   5.122 -  terms and theorems that stem from the hypothetical \<open>\<DEFINE>\<close> and \<open>\<NOTE>\<close> elements, transformed by the
   5.123 -  particular target policy (see @{cite \<open>\S4--5\<close> "Haftmann-Wenzel:2009"}
   5.124 -  for details).\<close>
   5.125 +  When a definitional package is finished, the auxiliary context is reset to
   5.126 +  the target context. The target now holds definitions for terms and theorems
   5.127 +  that stem from the hypothetical \<open>\<DEFINE>\<close> and \<open>\<NOTE>\<close> elements,
   5.128 +  transformed by the particular target policy (see @{cite \<open>\S4--5\<close>
   5.129 +  "Haftmann-Wenzel:2009"} for details).
   5.130 +\<close>
   5.131  
   5.132  text %mlref \<open>
   5.133    \begin{mldecls}
   5.134 @@ -103,50 +98,45 @@
   5.135      local_theory -> (string * thm list) * local_theory"} \\
   5.136    \end{mldecls}
   5.137  
   5.138 -  \<^descr> Type @{ML_type local_theory} represents local theories.
   5.139 -  Although this is merely an alias for @{ML_type Proof.context}, it is
   5.140 -  semantically a subtype of the same: a @{ML_type local_theory} holds
   5.141 -  target information as special context data.  Subtyping means that
   5.142 -  any value \<open>lthy:\<close>~@{ML_type local_theory} can be also used
   5.143 -  with operations on expecting a regular \<open>ctxt:\<close>~@{ML_type
   5.144 +  \<^descr> Type @{ML_type local_theory} represents local theories. Although this is
   5.145 +  merely an alias for @{ML_type Proof.context}, it is semantically a subtype
   5.146 +  of the same: a @{ML_type local_theory} holds target information as special
   5.147 +  context data. Subtyping means that any value \<open>lthy:\<close>~@{ML_type local_theory}
   5.148 +  can be also used with operations on expecting a regular \<open>ctxt:\<close>~@{ML_type
   5.149    Proof.context}.
   5.150  
   5.151 -  \<^descr> @{ML Named_Target.init}~\<open>before_exit name thy\<close>
   5.152 -  initializes a local theory derived from the given background theory.
   5.153 -  An empty name refers to a \<^emph>\<open>global theory\<close> context, and a
   5.154 -  non-empty name refers to a @{command locale} or @{command class}
   5.155 -  context (a fully-qualified internal name is expected here).  This is
   5.156 -  useful for experimentation --- normally the Isar toplevel already
   5.157 +  \<^descr> @{ML Named_Target.init}~\<open>before_exit name thy\<close> initializes a local theory
   5.158 +  derived from the given background theory. An empty name refers to a \<^emph>\<open>global
   5.159 +  theory\<close> context, and a non-empty name refers to a @{command locale} or
   5.160 +  @{command class} context (a fully-qualified internal name is expected here).
   5.161 +  This is useful for experimentation --- normally the Isar toplevel already
   5.162    takes care to initialize the local theory context.
   5.163  
   5.164 -  \<^descr> @{ML Local_Theory.define}~\<open>((b, mx), (a, rhs))
   5.165 -  lthy\<close> defines a local entity according to the specification that is
   5.166 -  given relatively to the current \<open>lthy\<close> context.  In
   5.167 -  particular the term of the RHS may refer to earlier local entities
   5.168 -  from the auxiliary context, or hypothetical parameters from the
   5.169 -  target context.  The result is the newly defined term (which is
   5.170 -  always a fixed variable with exactly the same name as specified for
   5.171 -  the LHS), together with an equational theorem that states the
   5.172 -  definition as a hypothetical fact.
   5.173 +  \<^descr> @{ML Local_Theory.define}~\<open>((b, mx), (a, rhs)) lthy\<close> defines a local
   5.174 +  entity according to the specification that is given relatively to the
   5.175 +  current \<open>lthy\<close> context. In particular the term of the RHS may refer to
   5.176 +  earlier local entities from the auxiliary context, or hypothetical
   5.177 +  parameters from the target context. The result is the newly defined term
   5.178 +  (which is always a fixed variable with exactly the same name as specified
   5.179 +  for the LHS), together with an equational theorem that states the definition
   5.180 +  as a hypothetical fact.
   5.181  
   5.182 -  Unless an explicit name binding is given for the RHS, the resulting
   5.183 -  fact will be called \<open>b_def\<close>.  Any given attributes are
   5.184 -  applied to that same fact --- immediately in the auxiliary context
   5.185 -  \<^emph>\<open>and\<close> in any transformed versions stemming from target-specific
   5.186 -  policies or any later interpretations of results from the target
   5.187 -  context (think of @{command locale} and @{command interpretation},
   5.188 -  for example).  This means that attributes should be usually plain
   5.189 -  declarations such as @{attribute simp}, while non-trivial rules like
   5.190 +  Unless an explicit name binding is given for the RHS, the resulting fact
   5.191 +  will be called \<open>b_def\<close>. Any given attributes are applied to that same fact
   5.192 +  --- immediately in the auxiliary context \<^emph>\<open>and\<close> in any transformed versions
   5.193 +  stemming from target-specific policies or any later interpretations of
   5.194 +  results from the target context (think of @{command locale} and @{command
   5.195 +  interpretation}, for example). This means that attributes should be usually
   5.196 +  plain declarations such as @{attribute simp}, while non-trivial rules like
   5.197    @{attribute simplified} are better avoided.
   5.198  
   5.199 -  \<^descr> @{ML Local_Theory.note}~\<open>(a, ths) lthy\<close> is
   5.200 -  analogous to @{ML Local_Theory.define}, but defines facts instead of
   5.201 -  terms.  There is also a slightly more general variant @{ML
   5.202 -  Local_Theory.notes} that defines several facts (with attribute
   5.203 -  expressions) simultaneously.
   5.204 +  \<^descr> @{ML Local_Theory.note}~\<open>(a, ths) lthy\<close> is analogous to @{ML
   5.205 +  Local_Theory.define}, but defines facts instead of terms. There is also a
   5.206 +  slightly more general variant @{ML Local_Theory.notes} that defines several
   5.207 +  facts (with attribute expressions) simultaneously.
   5.208  
   5.209 -  This is essentially the internal version of the @{command lemmas}
   5.210 -  command, or @{command declare} if an empty name binding is given.
   5.211 +  This is essentially the internal version of the @{command lemmas} command,
   5.212 +  or @{command declare} if an empty name binding is given.
   5.213  \<close>
   5.214  
   5.215  
     6.1 --- a/src/Doc/Implementation/Logic.thy	Tue Dec 15 14:41:47 2015 +0000
     6.2 +++ b/src/Doc/Implementation/Logic.thy	Wed Dec 16 17:30:30 2015 +0100
     6.3 @@ -7,110 +7,97 @@
     6.4  chapter \<open>Primitive logic \label{ch:logic}\<close>
     6.5  
     6.6  text \<open>
     6.7 -  The logical foundations of Isabelle/Isar are that of the Pure logic,
     6.8 -  which has been introduced as a Natural Deduction framework in
     6.9 -  @{cite paulson700}.  This is essentially the same logic as ``\<open>\<lambda>HOL\<close>'' in the more abstract setting of Pure Type Systems (PTS)
    6.10 -  @{cite "Barendregt-Geuvers:2001"}, although there are some key
    6.11 -  differences in the specific treatment of simple types in
    6.12 -  Isabelle/Pure.
    6.13 +  The logical foundations of Isabelle/Isar are that of the Pure logic, which
    6.14 +  has been introduced as a Natural Deduction framework in @{cite paulson700}.
    6.15 +  This is essentially the same logic as ``\<open>\<lambda>HOL\<close>'' in the more abstract
    6.16 +  setting of Pure Type Systems (PTS) @{cite "Barendregt-Geuvers:2001"},
    6.17 +  although there are some key differences in the specific treatment of simple
    6.18 +  types in Isabelle/Pure.
    6.19  
    6.20 -  Following type-theoretic parlance, the Pure logic consists of three
    6.21 -  levels of \<open>\<lambda>\<close>-calculus with corresponding arrows, \<open>\<Rightarrow>\<close> for syntactic function space (terms depending on terms), \<open>\<And>\<close> for universal quantification (proofs depending on terms), and
    6.22 -  \<open>\<Longrightarrow>\<close> for implication (proofs depending on proofs).
    6.23 +  Following type-theoretic parlance, the Pure logic consists of three levels
    6.24 +  of \<open>\<lambda>\<close>-calculus with corresponding arrows, \<open>\<Rightarrow>\<close> for syntactic function space
    6.25 +  (terms depending on terms), \<open>\<And>\<close> for universal quantification (proofs
    6.26 +  depending on terms), and \<open>\<Longrightarrow>\<close> for implication (proofs depending on proofs).
    6.27  
    6.28    Derivations are relative to a logical theory, which declares type
    6.29 -  constructors, constants, and axioms.  Theory declarations support
    6.30 -  schematic polymorphism, which is strictly speaking outside the
    6.31 -  logic.\<^footnote>\<open>This is the deeper logical reason, why the theory
    6.32 -  context \<open>\<Theta>\<close> is separate from the proof context \<open>\<Gamma>\<close>
    6.33 -  of the core calculus: type constructors, term constants, and facts
    6.34 -  (proof constants) may involve arbitrary type schemes, but the type
    6.35 -  of a locally fixed term parameter is also fixed!\<close>
    6.36 +  constructors, constants, and axioms. Theory declarations support schematic
    6.37 +  polymorphism, which is strictly speaking outside the logic.\<^footnote>\<open>This is the
    6.38 +  deeper logical reason, why the theory context \<open>\<Theta>\<close> is separate from the proof
    6.39 +  context \<open>\<Gamma>\<close> of the core calculus: type constructors, term constants, and
    6.40 +  facts (proof constants) may involve arbitrary type schemes, but the type of
    6.41 +  a locally fixed term parameter is also fixed!\<close>
    6.42  \<close>
    6.43  
    6.44  
    6.45  section \<open>Types \label{sec:types}\<close>
    6.46  
    6.47  text \<open>
    6.48 -  The language of types is an uninterpreted order-sorted first-order
    6.49 -  algebra; types are qualified by ordered type classes.
    6.50 +  The language of types is an uninterpreted order-sorted first-order algebra;
    6.51 +  types are qualified by ordered type classes.
    6.52  
    6.53    \<^medskip>
    6.54 -  A \<^emph>\<open>type class\<close> is an abstract syntactic entity
    6.55 -  declared in the theory context.  The \<^emph>\<open>subclass relation\<close> \<open>c\<^sub>1 \<subseteq> c\<^sub>2\<close> is specified by stating an acyclic
    6.56 -  generating relation; the transitive closure is maintained
    6.57 -  internally.  The resulting relation is an ordering: reflexive,
    6.58 -  transitive, and antisymmetric.
    6.59 +  A \<^emph>\<open>type class\<close> is an abstract syntactic entity declared in the theory
    6.60 +  context. The \<^emph>\<open>subclass relation\<close> \<open>c\<^sub>1 \<subseteq> c\<^sub>2\<close> is specified by stating an
    6.61 +  acyclic generating relation; the transitive closure is maintained
    6.62 +  internally. The resulting relation is an ordering: reflexive, transitive,
    6.63 +  and antisymmetric.
    6.64  
    6.65 -  A \<^emph>\<open>sort\<close> is a list of type classes written as \<open>s = {c\<^sub>1,
    6.66 -  \<dots>, c\<^sub>m}\<close>, it represents symbolic intersection.  Notationally, the
    6.67 -  curly braces are omitted for singleton intersections, i.e.\ any
    6.68 -  class \<open>c\<close> may be read as a sort \<open>{c}\<close>.  The ordering
    6.69 -  on type classes is extended to sorts according to the meaning of
    6.70 -  intersections: \<open>{c\<^sub>1, \<dots> c\<^sub>m} \<subseteq> {d\<^sub>1, \<dots>, d\<^sub>n}\<close> iff \<open>\<forall>j. \<exists>i. c\<^sub>i \<subseteq> d\<^sub>j\<close>.  The empty intersection \<open>{}\<close> refers to
    6.71 -  the universal sort, which is the largest element wrt.\ the sort
    6.72 -  order.  Thus \<open>{}\<close> represents the ``full sort'', not the
    6.73 -  empty one!  The intersection of all (finitely many) classes declared
    6.74 -  in the current theory is the least element wrt.\ the sort ordering.
    6.75 +  A \<^emph>\<open>sort\<close> is a list of type classes written as \<open>s = {c\<^sub>1, \<dots>, c\<^sub>m}\<close>, it
    6.76 +  represents symbolic intersection. Notationally, the curly braces are omitted
    6.77 +  for singleton intersections, i.e.\ any class \<open>c\<close> may be read as a sort
    6.78 +  \<open>{c}\<close>. The ordering on type classes is extended to sorts according to the
    6.79 +  meaning of intersections: \<open>{c\<^sub>1, \<dots> c\<^sub>m} \<subseteq> {d\<^sub>1, \<dots>, d\<^sub>n}\<close> iff \<open>\<forall>j. \<exists>i. c\<^sub>i \<subseteq>
    6.80 +  d\<^sub>j\<close>. The empty intersection \<open>{}\<close> refers to the universal sort, which is the
    6.81 +  largest element wrt.\ the sort order. Thus \<open>{}\<close> represents the ``full
    6.82 +  sort'', not the empty one! The intersection of all (finitely many) classes
    6.83 +  declared in the current theory is the least element wrt.\ the sort ordering.
    6.84  
    6.85    \<^medskip>
    6.86 -  A \<^emph>\<open>fixed type variable\<close> is a pair of a basic name
    6.87 -  (starting with a \<open>'\<close> character) and a sort constraint, e.g.\
    6.88 -  \<open>('a, s)\<close> which is usually printed as \<open>\<alpha>\<^sub>s\<close>.
    6.89 -  A \<^emph>\<open>schematic type variable\<close> is a pair of an indexname and a
    6.90 -  sort constraint, e.g.\ \<open>(('a, 0), s)\<close> which is usually
    6.91 -  printed as \<open>?\<alpha>\<^sub>s\<close>.
    6.92 +  A \<^emph>\<open>fixed type variable\<close> is a pair of a basic name (starting with a \<open>'\<close>
    6.93 +  character) and a sort constraint, e.g.\ \<open>('a, s)\<close> which is usually printed
    6.94 +  as \<open>\<alpha>\<^sub>s\<close>. A \<^emph>\<open>schematic type variable\<close> is a pair of an indexname and a sort
    6.95 +  constraint, e.g.\ \<open>(('a, 0), s)\<close> which is usually printed as \<open>?\<alpha>\<^sub>s\<close>.
    6.96  
    6.97 -  Note that \<^emph>\<open>all\<close> syntactic components contribute to the identity
    6.98 -  of type variables: basic name, index, and sort constraint.  The core
    6.99 -  logic handles type variables with the same name but different sorts
   6.100 -  as different, although the type-inference layer (which is outside
   6.101 -  the core) rejects anything like that.
   6.102 +  Note that \<^emph>\<open>all\<close> syntactic components contribute to the identity of type
   6.103 +  variables: basic name, index, and sort constraint. The core logic handles
   6.104 +  type variables with the same name but different sorts as different, although
   6.105 +  the type-inference layer (which is outside the core) rejects anything like
   6.106 +  that.
   6.107  
   6.108 -  A \<^emph>\<open>type constructor\<close> \<open>\<kappa>\<close> is a \<open>k\<close>-ary operator
   6.109 -  on types declared in the theory.  Type constructor application is
   6.110 -  written postfix as \<open>(\<alpha>\<^sub>1, \<dots>, \<alpha>\<^sub>k)\<kappa>\<close>.  For
   6.111 -  \<open>k = 0\<close> the argument tuple is omitted, e.g.\ \<open>prop\<close>
   6.112 -  instead of \<open>()prop\<close>.  For \<open>k = 1\<close> the parentheses
   6.113 -  are omitted, e.g.\ \<open>\<alpha> list\<close> instead of \<open>(\<alpha>)list\<close>.
   6.114 -  Further notation is provided for specific constructors, notably the
   6.115 -  right-associative infix \<open>\<alpha> \<Rightarrow> \<beta>\<close> instead of \<open>(\<alpha>,
   6.116 -  \<beta>)fun\<close>.
   6.117 +  A \<^emph>\<open>type constructor\<close> \<open>\<kappa>\<close> is a \<open>k\<close>-ary operator on types declared in the
   6.118 +  theory. Type constructor application is written postfix as \<open>(\<alpha>\<^sub>1, \<dots>, \<alpha>\<^sub>k)\<kappa>\<close>.
   6.119 +  For \<open>k = 0\<close> the argument tuple is omitted, e.g.\ \<open>prop\<close> instead of \<open>()prop\<close>.
   6.120 +  For \<open>k = 1\<close> the parentheses are omitted, e.g.\ \<open>\<alpha> list\<close> instead of
   6.121 +  \<open>(\<alpha>)list\<close>. Further notation is provided for specific constructors, notably
   6.122 +  the right-associative infix \<open>\<alpha> \<Rightarrow> \<beta>\<close> instead of \<open>(\<alpha>, \<beta>)fun\<close>.
   6.123    
   6.124 -  The logical category \<^emph>\<open>type\<close> is defined inductively over type
   6.125 -  variables and type constructors as follows: \<open>\<tau> = \<alpha>\<^sub>s | ?\<alpha>\<^sub>s |
   6.126 -  (\<tau>\<^sub>1, \<dots>, \<tau>\<^sub>k)\<kappa>\<close>.
   6.127 +  The logical category \<^emph>\<open>type\<close> is defined inductively over type variables and
   6.128 +  type constructors as follows: \<open>\<tau> = \<alpha>\<^sub>s | ?\<alpha>\<^sub>s | (\<tau>\<^sub>1, \<dots>, \<tau>\<^sub>k)\<kappa>\<close>.
   6.129  
   6.130 -  A \<^emph>\<open>type abbreviation\<close> is a syntactic definition \<open>(\<^vec>\<alpha>)\<kappa> = \<tau>\<close> of an arbitrary type expression \<open>\<tau>\<close> over
   6.131 -  variables \<open>\<^vec>\<alpha>\<close>.  Type abbreviations appear as type
   6.132 -  constructors in the syntax, but are expanded before entering the
   6.133 -  logical core.
   6.134 +  A \<^emph>\<open>type abbreviation\<close> is a syntactic definition \<open>(\<^vec>\<alpha>)\<kappa> = \<tau>\<close> of an
   6.135 +  arbitrary type expression \<open>\<tau>\<close> over variables \<open>\<^vec>\<alpha>\<close>. Type abbreviations
   6.136 +  appear as type constructors in the syntax, but are expanded before entering
   6.137 +  the logical core.
   6.138  
   6.139 -  A \<^emph>\<open>type arity\<close> declares the image behavior of a type
   6.140 -  constructor wrt.\ the algebra of sorts: \<open>\<kappa> :: (s\<^sub>1, \<dots>,
   6.141 -  s\<^sub>k)s\<close> means that \<open>(\<tau>\<^sub>1, \<dots>, \<tau>\<^sub>k)\<kappa>\<close> is
   6.142 -  of sort \<open>s\<close> if every argument type \<open>\<tau>\<^sub>i\<close> is
   6.143 -  of sort \<open>s\<^sub>i\<close>.  Arity declarations are implicitly
   6.144 -  completed, i.e.\ \<open>\<kappa> :: (\<^vec>s)c\<close> entails \<open>\<kappa> ::
   6.145 +  A \<^emph>\<open>type arity\<close> declares the image behavior of a type constructor wrt.\ the
   6.146 +  algebra of sorts: \<open>\<kappa> :: (s\<^sub>1, \<dots>, s\<^sub>k)s\<close> means that \<open>(\<tau>\<^sub>1, \<dots>, \<tau>\<^sub>k)\<kappa>\<close> is of
   6.147 +  sort \<open>s\<close> if every argument type \<open>\<tau>\<^sub>i\<close> is of sort \<open>s\<^sub>i\<close>. Arity declarations
   6.148 +  are implicitly completed, i.e.\ \<open>\<kappa> :: (\<^vec>s)c\<close> entails \<open>\<kappa> ::
   6.149    (\<^vec>s)c'\<close> for any \<open>c' \<supseteq> c\<close>.
   6.150  
   6.151    \<^medskip>
   6.152 -  The sort algebra is always maintained as \<^emph>\<open>coregular\<close>,
   6.153 -  which means that type arities are consistent with the subclass
   6.154 -  relation: for any type constructor \<open>\<kappa>\<close>, and classes \<open>c\<^sub>1 \<subseteq> c\<^sub>2\<close>, and arities \<open>\<kappa> ::
   6.155 -  (\<^vec>s\<^sub>1)c\<^sub>1\<close> and \<open>\<kappa> ::
   6.156 -  (\<^vec>s\<^sub>2)c\<^sub>2\<close> holds \<open>\<^vec>s\<^sub>1 \<subseteq>
   6.157 -  \<^vec>s\<^sub>2\<close> component-wise.
   6.158 +  The sort algebra is always maintained as \<^emph>\<open>coregular\<close>, which means that type
   6.159 +  arities are consistent with the subclass relation: for any type constructor
   6.160 +  \<open>\<kappa>\<close>, and classes \<open>c\<^sub>1 \<subseteq> c\<^sub>2\<close>, and arities \<open>\<kappa> :: (\<^vec>s\<^sub>1)c\<^sub>1\<close> and \<open>\<kappa> ::
   6.161 +  (\<^vec>s\<^sub>2)c\<^sub>2\<close> holds \<open>\<^vec>s\<^sub>1 \<subseteq> \<^vec>s\<^sub>2\<close> component-wise.
   6.162  
   6.163    The key property of a coregular order-sorted algebra is that sort
   6.164    constraints can be solved in a most general fashion: for each type
   6.165 -  constructor \<open>\<kappa>\<close> and sort \<open>s\<close> there is a most general
   6.166 -  vector of argument sorts \<open>(s\<^sub>1, \<dots>, s\<^sub>k)\<close> such
   6.167 -  that a type scheme \<open>(\<alpha>\<^bsub>s\<^sub>1\<^esub>, \<dots>,
   6.168 -  \<alpha>\<^bsub>s\<^sub>k\<^esub>)\<kappa>\<close> is of sort \<open>s\<close>.
   6.169 -  Consequently, type unification has most general solutions (modulo
   6.170 -  equivalence of sorts), so type-inference produces primary types as
   6.171 -  expected @{cite "nipkow-prehofer"}.
   6.172 +  constructor \<open>\<kappa>\<close> and sort \<open>s\<close> there is a most general vector of argument
   6.173 +  sorts \<open>(s\<^sub>1, \<dots>, s\<^sub>k)\<close> such that a type scheme \<open>(\<alpha>\<^bsub>s\<^sub>1\<^esub>, \<dots>, \<alpha>\<^bsub>s\<^sub>k\<^esub>)\<kappa>\<close> is of
   6.174 +  sort \<open>s\<close>. Consequently, type unification has most general solutions (modulo
   6.175 +  equivalence of sorts), so type-inference produces primary types as expected
   6.176 +  @{cite "nipkow-prehofer"}.
   6.177  \<close>
   6.178  
   6.179  text %mlref \<open>
   6.180 @@ -135,48 +122,42 @@
   6.181  
   6.182    \<^descr> Type @{ML_type class} represents type classes.
   6.183  
   6.184 -  \<^descr> Type @{ML_type sort} represents sorts, i.e.\ finite
   6.185 -  intersections of classes.  The empty list @{ML "[]: sort"} refers to
   6.186 -  the empty class intersection, i.e.\ the ``full sort''.
   6.187 +  \<^descr> Type @{ML_type sort} represents sorts, i.e.\ finite intersections of
   6.188 +  classes. The empty list @{ML "[]: sort"} refers to the empty class
   6.189 +  intersection, i.e.\ the ``full sort''.
   6.190  
   6.191 -  \<^descr> Type @{ML_type arity} represents type arities.  A triple
   6.192 -  \<open>(\<kappa>, \<^vec>s, s) : arity\<close> represents \<open>\<kappa> ::
   6.193 -  (\<^vec>s)s\<close> as described above.
   6.194 +  \<^descr> Type @{ML_type arity} represents type arities. A triple \<open>(\<kappa>, \<^vec>s, s)
   6.195 +  : arity\<close> represents \<open>\<kappa> :: (\<^vec>s)s\<close> as described above.
   6.196  
   6.197 -  \<^descr> Type @{ML_type typ} represents types; this is a datatype with
   6.198 -  constructors @{ML TFree}, @{ML TVar}, @{ML Type}.
   6.199 +  \<^descr> Type @{ML_type typ} represents types; this is a datatype with constructors
   6.200 +  @{ML TFree}, @{ML TVar}, @{ML Type}.
   6.201  
   6.202 -  \<^descr> @{ML Term.map_atyps}~\<open>f \<tau>\<close> applies the mapping \<open>f\<close> to all atomic types (@{ML TFree}, @{ML TVar}) occurring in
   6.203 -  \<open>\<tau>\<close>.
   6.204 +  \<^descr> @{ML Term.map_atyps}~\<open>f \<tau>\<close> applies the mapping \<open>f\<close> to all atomic types
   6.205 +  (@{ML TFree}, @{ML TVar}) occurring in \<open>\<tau>\<close>.
   6.206  
   6.207 -  \<^descr> @{ML Term.fold_atyps}~\<open>f \<tau>\<close> iterates the operation
   6.208 -  \<open>f\<close> over all occurrences of atomic types (@{ML TFree}, @{ML
   6.209 -  TVar}) in \<open>\<tau>\<close>; the type structure is traversed from left to
   6.210 -  right.
   6.211 +  \<^descr> @{ML Term.fold_atyps}~\<open>f \<tau>\<close> iterates the operation \<open>f\<close> over all
   6.212 +  occurrences of atomic types (@{ML TFree}, @{ML TVar}) in \<open>\<tau>\<close>; the type
   6.213 +  structure is traversed from left to right.
   6.214  
   6.215 -  \<^descr> @{ML Sign.subsort}~\<open>thy (s\<^sub>1, s\<^sub>2)\<close>
   6.216 -  tests the subsort relation \<open>s\<^sub>1 \<subseteq> s\<^sub>2\<close>.
   6.217 +  \<^descr> @{ML Sign.subsort}~\<open>thy (s\<^sub>1, s\<^sub>2)\<close> tests the subsort relation \<open>s\<^sub>1 \<subseteq>
   6.218 +  s\<^sub>2\<close>.
   6.219  
   6.220 -  \<^descr> @{ML Sign.of_sort}~\<open>thy (\<tau>, s)\<close> tests whether type
   6.221 -  \<open>\<tau>\<close> is of sort \<open>s\<close>.
   6.222 +  \<^descr> @{ML Sign.of_sort}~\<open>thy (\<tau>, s)\<close> tests whether type \<open>\<tau>\<close> is of sort \<open>s\<close>.
   6.223  
   6.224 -  \<^descr> @{ML Sign.add_type}~\<open>ctxt (\<kappa>, k, mx)\<close> declares a
   6.225 -  new type constructors \<open>\<kappa>\<close> with \<open>k\<close> arguments and
   6.226 -  optional mixfix syntax.
   6.227 +  \<^descr> @{ML Sign.add_type}~\<open>ctxt (\<kappa>, k, mx)\<close> declares a new type constructors \<open>\<kappa>\<close>
   6.228 +  with \<open>k\<close> arguments and optional mixfix syntax.
   6.229  
   6.230 -  \<^descr> @{ML Sign.add_type_abbrev}~\<open>ctxt (\<kappa>, \<^vec>\<alpha>, \<tau>)\<close>
   6.231 -  defines a new type abbreviation \<open>(\<^vec>\<alpha>)\<kappa> = \<tau>\<close>.
   6.232 +  \<^descr> @{ML Sign.add_type_abbrev}~\<open>ctxt (\<kappa>, \<^vec>\<alpha>, \<tau>)\<close> defines a new type
   6.233 +  abbreviation \<open>(\<^vec>\<alpha>)\<kappa> = \<tau>\<close>.
   6.234  
   6.235 -  \<^descr> @{ML Sign.primitive_class}~\<open>(c, [c\<^sub>1, \<dots>,
   6.236 -  c\<^sub>n])\<close> declares a new class \<open>c\<close>, together with class
   6.237 -  relations \<open>c \<subseteq> c\<^sub>i\<close>, for \<open>i = 1, \<dots>, n\<close>.
   6.238 +  \<^descr> @{ML Sign.primitive_class}~\<open>(c, [c\<^sub>1, \<dots>, c\<^sub>n])\<close> declares a new class \<open>c\<close>,
   6.239 +  together with class relations \<open>c \<subseteq> c\<^sub>i\<close>, for \<open>i = 1, \<dots>, n\<close>.
   6.240  
   6.241 -  \<^descr> @{ML Sign.primitive_classrel}~\<open>(c\<^sub>1,
   6.242 -  c\<^sub>2)\<close> declares the class relation \<open>c\<^sub>1 \<subseteq>
   6.243 -  c\<^sub>2\<close>.
   6.244 +  \<^descr> @{ML Sign.primitive_classrel}~\<open>(c\<^sub>1, c\<^sub>2)\<close> declares the class relation
   6.245 +  \<open>c\<^sub>1 \<subseteq> c\<^sub>2\<close>.
   6.246  
   6.247 -  \<^descr> @{ML Sign.primitive_arity}~\<open>(\<kappa>, \<^vec>s, s)\<close> declares
   6.248 -  the arity \<open>\<kappa> :: (\<^vec>s)s\<close>.
   6.249 +  \<^descr> @{ML Sign.primitive_arity}~\<open>(\<kappa>, \<^vec>s, s)\<close> declares the arity \<open>\<kappa> ::
   6.250 +  (\<^vec>s)s\<close>.
   6.251  \<close>
   6.252  
   6.253  text %mlantiq \<open>
   6.254 @@ -201,92 +182,84 @@
   6.255    @@{ML_antiquotation typ} type
   6.256    \<close>}
   6.257  
   6.258 -  \<^descr> \<open>@{class c}\<close> inlines the internalized class \<open>c\<close> --- as @{ML_type string} literal.
   6.259 -
   6.260 -  \<^descr> \<open>@{sort s}\<close> inlines the internalized sort \<open>s\<close>
   6.261 -  --- as @{ML_type "string list"} literal.
   6.262 -
   6.263 -  \<^descr> \<open>@{type_name c}\<close> inlines the internalized type
   6.264 -  constructor \<open>c\<close> --- as @{ML_type string} literal.
   6.265 -
   6.266 -  \<^descr> \<open>@{type_abbrev c}\<close> inlines the internalized type
   6.267 -  abbreviation \<open>c\<close> --- as @{ML_type string} literal.
   6.268 -
   6.269 -  \<^descr> \<open>@{nonterminal c}\<close> inlines the internalized syntactic
   6.270 -  type~/ grammar nonterminal \<open>c\<close> --- as @{ML_type string}
   6.271 +  \<^descr> \<open>@{class c}\<close> inlines the internalized class \<open>c\<close> --- as @{ML_type string}
   6.272    literal.
   6.273  
   6.274 -  \<^descr> \<open>@{typ \<tau>}\<close> inlines the internalized type \<open>\<tau>\<close>
   6.275 -  --- as constructor term for datatype @{ML_type typ}.
   6.276 +  \<^descr> \<open>@{sort s}\<close> inlines the internalized sort \<open>s\<close> --- as @{ML_type "string
   6.277 +  list"} literal.
   6.278 +
   6.279 +  \<^descr> \<open>@{type_name c}\<close> inlines the internalized type constructor \<open>c\<close> --- as
   6.280 +  @{ML_type string} literal.
   6.281 +
   6.282 +  \<^descr> \<open>@{type_abbrev c}\<close> inlines the internalized type abbreviation \<open>c\<close> --- as
   6.283 +  @{ML_type string} literal.
   6.284 +
   6.285 +  \<^descr> \<open>@{nonterminal c}\<close> inlines the internalized syntactic type~/ grammar
   6.286 +  nonterminal \<open>c\<close> --- as @{ML_type string} literal.
   6.287 +
   6.288 +  \<^descr> \<open>@{typ \<tau>}\<close> inlines the internalized type \<open>\<tau>\<close> --- as constructor term for
   6.289 +  datatype @{ML_type typ}.
   6.290  \<close>
   6.291  
   6.292  
   6.293  section \<open>Terms \label{sec:terms}\<close>
   6.294  
   6.295  text \<open>
   6.296 -  The language of terms is that of simply-typed \<open>\<lambda>\<close>-calculus
   6.297 -  with de-Bruijn indices for bound variables (cf.\ @{cite debruijn72}
   6.298 -  or @{cite "paulson-ml2"}), with the types being determined by the
   6.299 -  corresponding binders.  In contrast, free variables and constants
   6.300 -  have an explicit name and type in each occurrence.
   6.301 +  The language of terms is that of simply-typed \<open>\<lambda>\<close>-calculus with de-Bruijn
   6.302 +  indices for bound variables (cf.\ @{cite debruijn72} or @{cite
   6.303 +  "paulson-ml2"}), with the types being determined by the corresponding
   6.304 +  binders. In contrast, free variables and constants have an explicit name and
   6.305 +  type in each occurrence.
   6.306  
   6.307    \<^medskip>
   6.308 -  A \<^emph>\<open>bound variable\<close> is a natural number \<open>b\<close>,
   6.309 -  which accounts for the number of intermediate binders between the
   6.310 -  variable occurrence in the body and its binding position.  For
   6.311 -  example, the de-Bruijn term \<open>\<lambda>\<^bsub>bool\<^esub>. \<lambda>\<^bsub>bool\<^esub>. 1 \<and> 0\<close> would
   6.312 -  correspond to \<open>\<lambda>x\<^bsub>bool\<^esub>. \<lambda>y\<^bsub>bool\<^esub>. x \<and> y\<close> in a named
   6.313 -  representation.  Note that a bound variable may be represented by
   6.314 -  different de-Bruijn indices at different occurrences, depending on
   6.315 -  the nesting of abstractions.
   6.316 +  A \<^emph>\<open>bound variable\<close> is a natural number \<open>b\<close>, which accounts for the number
   6.317 +  of intermediate binders between the variable occurrence in the body and its
   6.318 +  binding position. For example, the de-Bruijn term \<open>\<lambda>\<^bsub>bool\<^esub>. \<lambda>\<^bsub>bool\<^esub>. 1 \<and> 0\<close>
   6.319 +  would correspond to \<open>\<lambda>x\<^bsub>bool\<^esub>. \<lambda>y\<^bsub>bool\<^esub>. x \<and> y\<close> in a named representation.
   6.320 +  Note that a bound variable may be represented by different de-Bruijn indices
   6.321 +  at different occurrences, depending on the nesting of abstractions.
   6.322  
   6.323 -  A \<^emph>\<open>loose variable\<close> is a bound variable that is outside the
   6.324 -  scope of local binders.  The types (and names) for loose variables
   6.325 -  can be managed as a separate context, that is maintained as a stack
   6.326 -  of hypothetical binders.  The core logic operates on closed terms,
   6.327 -  without any loose variables.
   6.328 +  A \<^emph>\<open>loose variable\<close> is a bound variable that is outside the scope of local
   6.329 +  binders. The types (and names) for loose variables can be managed as a
   6.330 +  separate context, that is maintained as a stack of hypothetical binders. The
   6.331 +  core logic operates on closed terms, without any loose variables.
   6.332  
   6.333 -  A \<^emph>\<open>fixed variable\<close> is a pair of a basic name and a type, e.g.\
   6.334 -  \<open>(x, \<tau>)\<close> which is usually printed \<open>x\<^sub>\<tau>\<close> here.  A
   6.335 -  \<^emph>\<open>schematic variable\<close> is a pair of an indexname and a type,
   6.336 -  e.g.\ \<open>((x, 0), \<tau>)\<close> which is likewise printed as \<open>?x\<^sub>\<tau>\<close>.
   6.337 +  A \<^emph>\<open>fixed variable\<close> is a pair of a basic name and a type, e.g.\ \<open>(x, \<tau>)\<close>
   6.338 +  which is usually printed \<open>x\<^sub>\<tau>\<close> here. A \<^emph>\<open>schematic variable\<close> is a pair of an
   6.339 +  indexname and a type, e.g.\ \<open>((x, 0), \<tau>)\<close> which is likewise printed as
   6.340 +  \<open>?x\<^sub>\<tau>\<close>.
   6.341  
   6.342    \<^medskip>
   6.343 -  A \<^emph>\<open>constant\<close> is a pair of a basic name and a type,
   6.344 -  e.g.\ \<open>(c, \<tau>)\<close> which is usually printed as \<open>c\<^sub>\<tau>\<close>
   6.345 -  here.  Constants are declared in the context as polymorphic families
   6.346 -  \<open>c :: \<sigma>\<close>, meaning that all substitution instances \<open>c\<^sub>\<tau>\<close> for \<open>\<tau> = \<sigma>\<vartheta>\<close> are valid.
   6.347 +  A \<^emph>\<open>constant\<close> is a pair of a basic name and a type, e.g.\ \<open>(c, \<tau>)\<close> which is
   6.348 +  usually printed as \<open>c\<^sub>\<tau>\<close> here. Constants are declared in the context as
   6.349 +  polymorphic families \<open>c :: \<sigma>\<close>, meaning that all substitution instances \<open>c\<^sub>\<tau>\<close>
   6.350 +  for \<open>\<tau> = \<sigma>\<vartheta>\<close> are valid.
   6.351  
   6.352 -  The vector of \<^emph>\<open>type arguments\<close> of constant \<open>c\<^sub>\<tau>\<close> wrt.\
   6.353 -  the declaration \<open>c :: \<sigma>\<close> is defined as the codomain of the
   6.354 -  matcher \<open>\<vartheta> = {?\<alpha>\<^sub>1 \<mapsto> \<tau>\<^sub>1, \<dots>, ?\<alpha>\<^sub>n \<mapsto> \<tau>\<^sub>n}\<close> presented in
   6.355 -  canonical order \<open>(\<tau>\<^sub>1, \<dots>, \<tau>\<^sub>n)\<close>, corresponding to the
   6.356 -  left-to-right occurrences of the \<open>\<alpha>\<^sub>i\<close> in \<open>\<sigma>\<close>.
   6.357 -  Within a given theory context, there is a one-to-one correspondence
   6.358 -  between any constant \<open>c\<^sub>\<tau>\<close> and the application \<open>c(\<tau>\<^sub>1,
   6.359 -  \<dots>, \<tau>\<^sub>n)\<close> of its type arguments.  For example, with \<open>plus :: \<alpha>
   6.360 -  \<Rightarrow> \<alpha> \<Rightarrow> \<alpha>\<close>, the instance \<open>plus\<^bsub>nat \<Rightarrow> nat \<Rightarrow> nat\<^esub>\<close> corresponds to
   6.361 +  The vector of \<^emph>\<open>type arguments\<close> of constant \<open>c\<^sub>\<tau>\<close> wrt.\ the declaration \<open>c
   6.362 +  :: \<sigma>\<close> is defined as the codomain of the matcher \<open>\<vartheta> = {?\<alpha>\<^sub>1 \<mapsto> \<tau>\<^sub>1,
   6.363 +  \<dots>, ?\<alpha>\<^sub>n \<mapsto> \<tau>\<^sub>n}\<close> presented in canonical order \<open>(\<tau>\<^sub>1, \<dots>, \<tau>\<^sub>n)\<close>, corresponding
   6.364 +  to the left-to-right occurrences of the \<open>\<alpha>\<^sub>i\<close> in \<open>\<sigma>\<close>. Within a given theory
   6.365 +  context, there is a one-to-one correspondence between any constant \<open>c\<^sub>\<tau>\<close> and
   6.366 +  the application \<open>c(\<tau>\<^sub>1, \<dots>, \<tau>\<^sub>n)\<close> of its type arguments. For example, with
   6.367 +  \<open>plus :: \<alpha> \<Rightarrow> \<alpha> \<Rightarrow> \<alpha>\<close>, the instance \<open>plus\<^bsub>nat \<Rightarrow> nat \<Rightarrow> nat\<^esub>\<close> corresponds to
   6.368    \<open>plus(nat)\<close>.
   6.369  
   6.370 -  Constant declarations \<open>c :: \<sigma>\<close> may contain sort constraints
   6.371 -  for type variables in \<open>\<sigma>\<close>.  These are observed by
   6.372 -  type-inference as expected, but \<^emph>\<open>ignored\<close> by the core logic.
   6.373 -  This means the primitive logic is able to reason with instances of
   6.374 -  polymorphic constants that the user-level type-checker would reject
   6.375 -  due to violation of type class restrictions.
   6.376 +  Constant declarations \<open>c :: \<sigma>\<close> may contain sort constraints for type
   6.377 +  variables in \<open>\<sigma>\<close>. These are observed by type-inference as expected, but
   6.378 +  \<^emph>\<open>ignored\<close> by the core logic. This means the primitive logic is able to
   6.379 +  reason with instances of polymorphic constants that the user-level
   6.380 +  type-checker would reject due to violation of type class restrictions.
   6.381  
   6.382    \<^medskip>
   6.383 -  An \<^emph>\<open>atomic term\<close> is either a variable or constant.
   6.384 -  The logical category \<^emph>\<open>term\<close> is defined inductively over atomic
   6.385 -  terms, with abstraction and application as follows: \<open>t = b |
   6.386 -  x\<^sub>\<tau> | ?x\<^sub>\<tau> | c\<^sub>\<tau> | \<lambda>\<^sub>\<tau>. t | t\<^sub>1 t\<^sub>2\<close>.  Parsing and printing takes care of
   6.387 -  converting between an external representation with named bound
   6.388 -  variables.  Subsequently, we shall use the latter notation instead
   6.389 -  of internal de-Bruijn representation.
   6.390 +  An \<^emph>\<open>atomic term\<close> is either a variable or constant. The logical category
   6.391 +  \<^emph>\<open>term\<close> is defined inductively over atomic terms, with abstraction and
   6.392 +  application as follows: \<open>t = b | x\<^sub>\<tau> | ?x\<^sub>\<tau> | c\<^sub>\<tau> | \<lambda>\<^sub>\<tau>. t | t\<^sub>1 t\<^sub>2\<close>.
   6.393 +  Parsing and printing takes care of converting between an external
   6.394 +  representation with named bound variables. Subsequently, we shall use the
   6.395 +  latter notation instead of internal de-Bruijn representation.
   6.396  
   6.397 -  The inductive relation \<open>t :: \<tau>\<close> assigns a (unique) type to a
   6.398 -  term according to the structure of atomic terms, abstractions, and
   6.399 -  applications:
   6.400 +  The inductive relation \<open>t :: \<tau>\<close> assigns a (unique) type to a term according
   6.401 +  to the structure of atomic terms, abstractions, and applications:
   6.402    \[
   6.403    \infer{\<open>a\<^sub>\<tau> :: \<tau>\<close>}{}
   6.404    \qquad
   6.405 @@ -296,47 +269,46 @@
   6.406    \]
   6.407    A \<^emph>\<open>well-typed term\<close> is a term that can be typed according to these rules.
   6.408  
   6.409 -  Typing information can be omitted: type-inference is able to
   6.410 -  reconstruct the most general type of a raw term, while assigning
   6.411 -  most general types to all of its variables and constants.
   6.412 -  Type-inference depends on a context of type constraints for fixed
   6.413 -  variables, and declarations for polymorphic constants.
   6.414 +  Typing information can be omitted: type-inference is able to reconstruct the
   6.415 +  most general type of a raw term, while assigning most general types to all
   6.416 +  of its variables and constants. Type-inference depends on a context of type
   6.417 +  constraints for fixed variables, and declarations for polymorphic constants.
   6.418  
   6.419    The identity of atomic terms consists both of the name and the type
   6.420 -  component.  This means that different variables \<open>x\<^bsub>\<tau>\<^sub>1\<^esub>\<close> and \<open>x\<^bsub>\<tau>\<^sub>2\<^esub>\<close> may become the same after
   6.421 -  type instantiation.  Type-inference rejects variables of the same
   6.422 -  name, but different types.  In contrast, mixed instances of
   6.423 +  component. This means that different variables \<open>x\<^bsub>\<tau>\<^sub>1\<^esub>\<close> and \<open>x\<^bsub>\<tau>\<^sub>2\<^esub>\<close> may
   6.424 +  become the same after type instantiation. Type-inference rejects variables
   6.425 +  of the same name, but different types. In contrast, mixed instances of
   6.426    polymorphic constants occur routinely.
   6.427  
   6.428    \<^medskip>
   6.429 -  The \<^emph>\<open>hidden polymorphism\<close> of a term \<open>t :: \<sigma>\<close>
   6.430 -  is the set of type variables occurring in \<open>t\<close>, but not in
   6.431 -  its type \<open>\<sigma>\<close>.  This means that the term implicitly depends
   6.432 -  on type arguments that are not accounted in the result type, i.e.\
   6.433 -  there are different type instances \<open>t\<vartheta> :: \<sigma>\<close> and
   6.434 -  \<open>t\<vartheta>' :: \<sigma>\<close> with the same type.  This slightly
   6.435 -  pathological situation notoriously demands additional care.
   6.436 +  The \<^emph>\<open>hidden polymorphism\<close> of a term \<open>t :: \<sigma>\<close> is the set of type variables
   6.437 +  occurring in \<open>t\<close>, but not in its type \<open>\<sigma>\<close>. This means that the term
   6.438 +  implicitly depends on type arguments that are not accounted in the result
   6.439 +  type, i.e.\ there are different type instances \<open>t\<vartheta> :: \<sigma>\<close> and
   6.440 +  \<open>t\<vartheta>' :: \<sigma>\<close> with the same type. This slightly pathological
   6.441 +  situation notoriously demands additional care.
   6.442  
   6.443    \<^medskip>
   6.444 -  A \<^emph>\<open>term abbreviation\<close> is a syntactic definition \<open>c\<^sub>\<sigma> \<equiv> t\<close> of a closed term \<open>t\<close> of type \<open>\<sigma>\<close>,
   6.445 -  without any hidden polymorphism.  A term abbreviation looks like a
   6.446 -  constant in the syntax, but is expanded before entering the logical
   6.447 -  core.  Abbreviations are usually reverted when printing terms, using
   6.448 -  \<open>t \<rightarrow> c\<^sub>\<sigma>\<close> as rules for higher-order rewriting.
   6.449 +  A \<^emph>\<open>term abbreviation\<close> is a syntactic definition \<open>c\<^sub>\<sigma> \<equiv> t\<close> of a closed term
   6.450 +  \<open>t\<close> of type \<open>\<sigma>\<close>, without any hidden polymorphism. A term abbreviation looks
   6.451 +  like a constant in the syntax, but is expanded before entering the logical
   6.452 +  core. Abbreviations are usually reverted when printing terms, using \<open>t \<rightarrow>
   6.453 +  c\<^sub>\<sigma>\<close> as rules for higher-order rewriting.
   6.454  
   6.455    \<^medskip>
   6.456 -  Canonical operations on \<open>\<lambda>\<close>-terms include \<open>\<alpha>\<beta>\<eta>\<close>-conversion: \<open>\<alpha>\<close>-conversion refers to capture-free
   6.457 -  renaming of bound variables; \<open>\<beta>\<close>-conversion contracts an
   6.458 -  abstraction applied to an argument term, substituting the argument
   6.459 -  in the body: \<open>(\<lambda>x. b)a\<close> becomes \<open>b[a/x]\<close>; \<open>\<eta>\<close>-conversion contracts vacuous application-abstraction: \<open>\<lambda>x. f x\<close> becomes \<open>f\<close>, provided that the bound variable
   6.460 -  does not occur in \<open>f\<close>.
   6.461 +  Canonical operations on \<open>\<lambda>\<close>-terms include \<open>\<alpha>\<beta>\<eta>\<close>-conversion: \<open>\<alpha>\<close>-conversion
   6.462 +  refers to capture-free renaming of bound variables; \<open>\<beta>\<close>-conversion contracts
   6.463 +  an abstraction applied to an argument term, substituting the argument in the
   6.464 +  body: \<open>(\<lambda>x. b)a\<close> becomes \<open>b[a/x]\<close>; \<open>\<eta>\<close>-conversion contracts vacuous
   6.465 +  application-abstraction: \<open>\<lambda>x. f x\<close> becomes \<open>f\<close>, provided that the bound
   6.466 +  variable does not occur in \<open>f\<close>.
   6.467  
   6.468 -  Terms are normally treated modulo \<open>\<alpha>\<close>-conversion, which is
   6.469 -  implicit in the de-Bruijn representation.  Names for bound variables
   6.470 -  in abstractions are maintained separately as (meaningless) comments,
   6.471 -  mostly for parsing and printing.  Full \<open>\<alpha>\<beta>\<eta>\<close>-conversion is
   6.472 -  commonplace in various standard operations (\secref{sec:obj-rules})
   6.473 -  that are based on higher-order unification and matching.
   6.474 +  Terms are normally treated modulo \<open>\<alpha>\<close>-conversion, which is implicit in the
   6.475 +  de-Bruijn representation. Names for bound variables in abstractions are
   6.476 +  maintained separately as (meaningless) comments, mostly for parsing and
   6.477 +  printing. Full \<open>\<alpha>\<beta>\<eta>\<close>-conversion is commonplace in various standard
   6.478 +  operations (\secref{sec:obj-rules}) that are based on higher-order
   6.479 +  unification and matching.
   6.480  \<close>
   6.481  
   6.482  text %mlref \<open>
   6.483 @@ -361,56 +333,52 @@
   6.484    @{index_ML Sign.const_instance: "theory -> string * typ list -> typ"} \\
   6.485    \end{mldecls}
   6.486  
   6.487 -  \<^descr> Type @{ML_type term} represents de-Bruijn terms, with comments
   6.488 -  in abstractions, and explicitly named free variables and constants;
   6.489 -  this is a datatype with constructors @{index_ML Bound}, @{index_ML
   6.490 -  Free}, @{index_ML Var}, @{index_ML Const}, @{index_ML Abs},
   6.491 -  @{index_ML_op "$"}.
   6.492 +  \<^descr> Type @{ML_type term} represents de-Bruijn terms, with comments in
   6.493 +  abstractions, and explicitly named free variables and constants; this is a
   6.494 +  datatype with constructors @{index_ML Bound}, @{index_ML Free}, @{index_ML
   6.495 +  Var}, @{index_ML Const}, @{index_ML Abs}, @{index_ML_op "$"}.
   6.496  
   6.497 -  \<^descr> \<open>t\<close>~@{ML_text aconv}~\<open>u\<close> checks \<open>\<alpha>\<close>-equivalence of two terms.  This is the basic equality relation
   6.498 -  on type @{ML_type term}; raw datatype equality should only be used
   6.499 -  for operations related to parsing or printing!
   6.500 -
   6.501 -  \<^descr> @{ML Term.map_types}~\<open>f t\<close> applies the mapping \<open>f\<close> to all types occurring in \<open>t\<close>.
   6.502 +  \<^descr> \<open>t\<close>~@{ML_text aconv}~\<open>u\<close> checks \<open>\<alpha>\<close>-equivalence of two terms. This is the
   6.503 +  basic equality relation on type @{ML_type term}; raw datatype equality
   6.504 +  should only be used for operations related to parsing or printing!
   6.505  
   6.506 -  \<^descr> @{ML Term.fold_types}~\<open>f t\<close> iterates the operation
   6.507 -  \<open>f\<close> over all occurrences of types in \<open>t\<close>; the term
   6.508 -  structure is traversed from left to right.
   6.509 +  \<^descr> @{ML Term.map_types}~\<open>f t\<close> applies the mapping \<open>f\<close> to all types occurring
   6.510 +  in \<open>t\<close>.
   6.511 +
   6.512 +  \<^descr> @{ML Term.fold_types}~\<open>f t\<close> iterates the operation \<open>f\<close> over all
   6.513 +  occurrences of types in \<open>t\<close>; the term structure is traversed from left to
   6.514 +  right.
   6.515  
   6.516 -  \<^descr> @{ML Term.map_aterms}~\<open>f t\<close> applies the mapping \<open>f\<close> to all atomic terms (@{ML Bound}, @{ML Free}, @{ML Var}, @{ML
   6.517 -  Const}) occurring in \<open>t\<close>.
   6.518 +  \<^descr> @{ML Term.map_aterms}~\<open>f t\<close> applies the mapping \<open>f\<close> to all atomic terms
   6.519 +  (@{ML Bound}, @{ML Free}, @{ML Var}, @{ML Const}) occurring in \<open>t\<close>.
   6.520  
   6.521 -  \<^descr> @{ML Term.fold_aterms}~\<open>f t\<close> iterates the operation
   6.522 -  \<open>f\<close> over all occurrences of atomic terms (@{ML Bound}, @{ML
   6.523 -  Free}, @{ML Var}, @{ML Const}) in \<open>t\<close>; the term structure is
   6.524 -  traversed from left to right.
   6.525 +  \<^descr> @{ML Term.fold_aterms}~\<open>f t\<close> iterates the operation \<open>f\<close> over all
   6.526 +  occurrences of atomic terms (@{ML Bound}, @{ML Free}, @{ML Var}, @{ML
   6.527 +  Const}) in \<open>t\<close>; the term structure is traversed from left to right.
   6.528  
   6.529 -  \<^descr> @{ML fastype_of}~\<open>t\<close> determines the type of a
   6.530 -  well-typed term.  This operation is relatively slow, despite the
   6.531 -  omission of any sanity checks.
   6.532 +  \<^descr> @{ML fastype_of}~\<open>t\<close> determines the type of a well-typed term. This
   6.533 +  operation is relatively slow, despite the omission of any sanity checks.
   6.534  
   6.535 -  \<^descr> @{ML lambda}~\<open>a b\<close> produces an abstraction \<open>\<lambda>a. b\<close>, where occurrences of the atomic term \<open>a\<close> in the
   6.536 -  body \<open>b\<close> are replaced by bound variables.
   6.537 +  \<^descr> @{ML lambda}~\<open>a b\<close> produces an abstraction \<open>\<lambda>a. b\<close>, where occurrences of
   6.538 +  the atomic term \<open>a\<close> in the body \<open>b\<close> are replaced by bound variables.
   6.539  
   6.540 -  \<^descr> @{ML betapply}~\<open>(t, u)\<close> produces an application \<open>t u\<close>, with topmost \<open>\<beta>\<close>-conversion if \<open>t\<close> is an
   6.541 -  abstraction.
   6.542 +  \<^descr> @{ML betapply}~\<open>(t, u)\<close> produces an application \<open>t u\<close>, with topmost
   6.543 +  \<open>\<beta>\<close>-conversion if \<open>t\<close> is an abstraction.
   6.544  
   6.545 -  \<^descr> @{ML incr_boundvars}~\<open>j\<close> increments a term's dangling
   6.546 -  bound variables by the offset \<open>j\<close>.  This is required when
   6.547 -  moving a subterm into a context where it is enclosed by a different
   6.548 -  number of abstractions.  Bound variables with a matching abstraction
   6.549 -  are unaffected.
   6.550 +  \<^descr> @{ML incr_boundvars}~\<open>j\<close> increments a term's dangling bound variables by
   6.551 +  the offset \<open>j\<close>. This is required when moving a subterm into a context where
   6.552 +  it is enclosed by a different number of abstractions. Bound variables with a
   6.553 +  matching abstraction are unaffected.
   6.554  
   6.555 -  \<^descr> @{ML Sign.declare_const}~\<open>ctxt ((c, \<sigma>), mx)\<close> declares
   6.556 -  a new constant \<open>c :: \<sigma>\<close> with optional mixfix syntax.
   6.557 +  \<^descr> @{ML Sign.declare_const}~\<open>ctxt ((c, \<sigma>), mx)\<close> declares a new constant \<open>c ::
   6.558 +  \<sigma>\<close> with optional mixfix syntax.
   6.559  
   6.560 -  \<^descr> @{ML Sign.add_abbrev}~\<open>print_mode (c, t)\<close>
   6.561 -  introduces a new term abbreviation \<open>c \<equiv> t\<close>.
   6.562 +  \<^descr> @{ML Sign.add_abbrev}~\<open>print_mode (c, t)\<close> introduces a new term
   6.563 +  abbreviation \<open>c \<equiv> t\<close>.
   6.564  
   6.565 -  \<^descr> @{ML Sign.const_typargs}~\<open>thy (c, \<tau>)\<close> and @{ML
   6.566 -  Sign.const_instance}~\<open>thy (c, [\<tau>\<^sub>1, \<dots>, \<tau>\<^sub>n])\<close>
   6.567 -  convert between two representations of polymorphic constants: full
   6.568 -  type instance vs.\ compact type arguments form.
   6.569 +  \<^descr> @{ML Sign.const_typargs}~\<open>thy (c, \<tau>)\<close> and @{ML Sign.const_instance}~\<open>thy
   6.570 +  (c, [\<tau>\<^sub>1, \<dots>, \<tau>\<^sub>n])\<close> convert between two representations of polymorphic
   6.571 +  constants: full type instance vs.\ compact type arguments form.
   6.572  \<close>
   6.573  
   6.574  text %mlantiq \<open>
   6.575 @@ -433,33 +401,31 @@
   6.576    @@{ML_antiquotation prop} prop
   6.577    \<close>}
   6.578  
   6.579 -  \<^descr> \<open>@{const_name c}\<close> inlines the internalized logical
   6.580 -  constant name \<open>c\<close> --- as @{ML_type string} literal.
   6.581 +  \<^descr> \<open>@{const_name c}\<close> inlines the internalized logical constant name \<open>c\<close> ---
   6.582 +  as @{ML_type string} literal.
   6.583 +
   6.584 +  \<^descr> \<open>@{const_abbrev c}\<close> inlines the internalized abbreviated constant name \<open>c\<close>
   6.585 +  --- as @{ML_type string} literal.
   6.586  
   6.587 -  \<^descr> \<open>@{const_abbrev c}\<close> inlines the internalized
   6.588 -  abbreviated constant name \<open>c\<close> --- as @{ML_type string}
   6.589 -  literal.
   6.590 +  \<^descr> \<open>@{const c(\<^vec>\<tau>)}\<close> inlines the internalized constant \<open>c\<close> with precise
   6.591 +  type instantiation in the sense of @{ML Sign.const_instance} --- as @{ML
   6.592 +  Const} constructor term for datatype @{ML_type term}.
   6.593  
   6.594 -  \<^descr> \<open>@{const c(\<^vec>\<tau>)}\<close> inlines the internalized
   6.595 -  constant \<open>c\<close> with precise type instantiation in the sense of
   6.596 -  @{ML Sign.const_instance} --- as @{ML Const} constructor term for
   6.597 +  \<^descr> \<open>@{term t}\<close> inlines the internalized term \<open>t\<close> --- as constructor term for
   6.598    datatype @{ML_type term}.
   6.599  
   6.600 -  \<^descr> \<open>@{term t}\<close> inlines the internalized term \<open>t\<close>
   6.601 -  --- as constructor term for datatype @{ML_type term}.
   6.602 -
   6.603 -  \<^descr> \<open>@{prop \<phi>}\<close> inlines the internalized proposition
   6.604 -  \<open>\<phi>\<close> --- as constructor term for datatype @{ML_type term}.
   6.605 +  \<^descr> \<open>@{prop \<phi>}\<close> inlines the internalized proposition \<open>\<phi>\<close> --- as constructor
   6.606 +  term for datatype @{ML_type term}.
   6.607  \<close>
   6.608  
   6.609  
   6.610  section \<open>Theorems \label{sec:thms}\<close>
   6.611  
   6.612  text \<open>
   6.613 -  A \<^emph>\<open>proposition\<close> is a well-typed term of type \<open>prop\<close>, a
   6.614 -  \<^emph>\<open>theorem\<close> is a proven proposition (depending on a context of
   6.615 -  hypotheses and the background theory).  Primitive inferences include
   6.616 -  plain Natural Deduction rules for the primary connectives \<open>\<And>\<close> and \<open>\<Longrightarrow>\<close> of the framework.  There is also a builtin
   6.617 +  A \<^emph>\<open>proposition\<close> is a well-typed term of type \<open>prop\<close>, a \<^emph>\<open>theorem\<close> is a
   6.618 +  proven proposition (depending on a context of hypotheses and the background
   6.619 +  theory). Primitive inferences include plain Natural Deduction rules for the
   6.620 +  primary connectives \<open>\<And>\<close> and \<open>\<Longrightarrow>\<close> of the framework. There is also a builtin
   6.621    notion of equality/equivalence \<open>\<equiv>\<close>.
   6.622  \<close>
   6.623  
   6.624 @@ -467,16 +433,14 @@
   6.625  subsection \<open>Primitive connectives and rules \label{sec:prim-rules}\<close>
   6.626  
   6.627  text \<open>
   6.628 -  The theory \<open>Pure\<close> contains constant declarations for the
   6.629 -  primitive connectives \<open>\<And>\<close>, \<open>\<Longrightarrow>\<close>, and \<open>\<equiv>\<close> of
   6.630 -  the logical framework, see \figref{fig:pure-connectives}.  The
   6.631 -  derivability judgment \<open>A\<^sub>1, \<dots>, A\<^sub>n \<turnstile> B\<close> is
   6.632 -  defined inductively by the primitive inferences given in
   6.633 -  \figref{fig:prim-rules}, with the global restriction that the
   6.634 -  hypotheses must \<^emph>\<open>not\<close> contain any schematic variables.  The
   6.635 -  builtin equality is conceptually axiomatized as shown in
   6.636 -  \figref{fig:pure-equality}, although the implementation works
   6.637 -  directly with derived inferences.
   6.638 +  The theory \<open>Pure\<close> contains constant declarations for the primitive
   6.639 +  connectives \<open>\<And>\<close>, \<open>\<Longrightarrow>\<close>, and \<open>\<equiv>\<close> of the logical framework, see
   6.640 +  \figref{fig:pure-connectives}. The derivability judgment \<open>A\<^sub>1, \<dots>, A\<^sub>n \<turnstile> B\<close>
   6.641 +  is defined inductively by the primitive inferences given in
   6.642 +  \figref{fig:prim-rules}, with the global restriction that the hypotheses
   6.643 +  must \<^emph>\<open>not\<close> contain any schematic variables. The builtin equality is
   6.644 +  conceptually axiomatized as shown in \figref{fig:pure-equality}, although
   6.645 +  the implementation works directly with derived inferences.
   6.646  
   6.647    \begin{figure}[htb]
   6.648    \begin{center}
   6.649 @@ -523,26 +487,29 @@
   6.650    \end{center}
   6.651    \end{figure}
   6.652  
   6.653 -  The introduction and elimination rules for \<open>\<And>\<close> and \<open>\<Longrightarrow>\<close> are analogous to formation of dependently typed \<open>\<lambda>\<close>-terms representing the underlying proof objects.  Proof terms
   6.654 -  are irrelevant in the Pure logic, though; they cannot occur within
   6.655 -  propositions.  The system provides a runtime option to record
   6.656 +  The introduction and elimination rules for \<open>\<And>\<close> and \<open>\<Longrightarrow>\<close> are analogous to
   6.657 +  formation of dependently typed \<open>\<lambda>\<close>-terms representing the underlying proof
   6.658 +  objects. Proof terms are irrelevant in the Pure logic, though; they cannot
   6.659 +  occur within propositions. The system provides a runtime option to record
   6.660    explicit proof terms for primitive inferences, see also
   6.661 -  \secref{sec:proof-terms}.  Thus all three levels of \<open>\<lambda>\<close>-calculus become explicit: \<open>\<Rightarrow>\<close> for terms, and \<open>\<And>/\<Longrightarrow>\<close> for proofs (cf.\ @{cite "Berghofer-Nipkow:2000:TPHOL"}).
   6.662 +  \secref{sec:proof-terms}. Thus all three levels of \<open>\<lambda>\<close>-calculus become
   6.663 +  explicit: \<open>\<Rightarrow>\<close> for terms, and \<open>\<And>/\<Longrightarrow>\<close> for proofs (cf.\ @{cite
   6.664 +  "Berghofer-Nipkow:2000:TPHOL"}).
   6.665  
   6.666 -  Observe that locally fixed parameters (as in \<open>\<And>\<hyphen>intro\<close>) need not be recorded in the hypotheses, because
   6.667 -  the simple syntactic types of Pure are always inhabitable.
   6.668 -  ``Assumptions'' \<open>x :: \<tau>\<close> for type-membership are only
   6.669 -  present as long as some \<open>x\<^sub>\<tau>\<close> occurs in the statement
   6.670 -  body.\<^footnote>\<open>This is the key difference to ``\<open>\<lambda>HOL\<close>'' in
   6.671 -  the PTS framework @{cite "Barendregt-Geuvers:2001"}, where hypotheses
   6.672 -  \<open>x : A\<close> are treated uniformly for propositions and types.\<close>
   6.673 +  Observe that locally fixed parameters (as in \<open>\<And>\<hyphen>intro\<close>) need not be recorded
   6.674 +  in the hypotheses, because the simple syntactic types of Pure are always
   6.675 +  inhabitable. ``Assumptions'' \<open>x :: \<tau>\<close> for type-membership are only present
   6.676 +  as long as some \<open>x\<^sub>\<tau>\<close> occurs in the statement body.\<^footnote>\<open>This is the key
   6.677 +  difference to ``\<open>\<lambda>HOL\<close>'' in the PTS framework @{cite
   6.678 +  "Barendregt-Geuvers:2001"}, where hypotheses \<open>x : A\<close> are treated uniformly
   6.679 +  for propositions and types.\<close>
   6.680  
   6.681    \<^medskip>
   6.682 -  The axiomatization of a theory is implicitly closed by
   6.683 -  forming all instances of type and term variables: \<open>\<turnstile>
   6.684 -  A\<vartheta>\<close> holds for any substitution instance of an axiom
   6.685 -  \<open>\<turnstile> A\<close>.  By pushing substitutions through derivations
   6.686 -  inductively, we also get admissible \<open>generalize\<close> and \<open>instantiate\<close> rules as shown in \figref{fig:subst-rules}.
   6.687 +  The axiomatization of a theory is implicitly closed by forming all instances
   6.688 +  of type and term variables: \<open>\<turnstile> A\<vartheta>\<close> holds for any substitution
   6.689 +  instance of an axiom \<open>\<turnstile> A\<close>. By pushing substitutions through derivations
   6.690 +  inductively, we also get admissible \<open>generalize\<close> and \<open>instantiate\<close> rules as
   6.691 +  shown in \figref{fig:subst-rules}.
   6.692  
   6.693    \begin{figure}[htb]
   6.694    \begin{center}
   6.695 @@ -560,40 +527,39 @@
   6.696    \end{center}
   6.697    \end{figure}
   6.698  
   6.699 -  Note that \<open>instantiate\<close> does not require an explicit
   6.700 -  side-condition, because \<open>\<Gamma>\<close> may never contain schematic
   6.701 -  variables.
   6.702 +  Note that \<open>instantiate\<close> does not require an explicit side-condition, because
   6.703 +  \<open>\<Gamma>\<close> may never contain schematic variables.
   6.704  
   6.705 -  In principle, variables could be substituted in hypotheses as well,
   6.706 -  but this would disrupt the monotonicity of reasoning: deriving
   6.707 -  \<open>\<Gamma>\<vartheta> \<turnstile> B\<vartheta>\<close> from \<open>\<Gamma> \<turnstile> B\<close> is
   6.708 -  correct, but \<open>\<Gamma>\<vartheta> \<supseteq> \<Gamma>\<close> does not necessarily hold:
   6.709 -  the result belongs to a different proof context.
   6.710 +  In principle, variables could be substituted in hypotheses as well, but this
   6.711 +  would disrupt the monotonicity of reasoning: deriving \<open>\<Gamma>\<vartheta> \<turnstile>
   6.712 +  B\<vartheta>\<close> from \<open>\<Gamma> \<turnstile> B\<close> is correct, but \<open>\<Gamma>\<vartheta> \<supseteq> \<Gamma>\<close> does not
   6.713 +  necessarily hold: the result belongs to a different proof context.
   6.714  
   6.715    \<^medskip>
   6.716 -  An \<^emph>\<open>oracle\<close> is a function that produces axioms on the
   6.717 -  fly.  Logically, this is an instance of the \<open>axiom\<close> rule
   6.718 -  (\figref{fig:prim-rules}), but there is an operational difference.
   6.719 -  The system always records oracle invocations within derivations of
   6.720 -  theorems by a unique tag.
   6.721 +  An \<^emph>\<open>oracle\<close> is a function that produces axioms on the fly. Logically, this
   6.722 +  is an instance of the \<open>axiom\<close> rule (\figref{fig:prim-rules}), but there is
   6.723 +  an operational difference. The system always records oracle invocations
   6.724 +  within derivations of theorems by a unique tag.
   6.725  
   6.726 -  Axiomatizations should be limited to the bare minimum, typically as
   6.727 -  part of the initial logical basis of an object-logic formalization.
   6.728 -  Later on, theories are usually developed in a strictly definitional
   6.729 -  fashion, by stating only certain equalities over new constants.
   6.730 +  Axiomatizations should be limited to the bare minimum, typically as part of
   6.731 +  the initial logical basis of an object-logic formalization. Later on,
   6.732 +  theories are usually developed in a strictly definitional fashion, by
   6.733 +  stating only certain equalities over new constants.
   6.734  
   6.735 -  A \<^emph>\<open>simple definition\<close> consists of a constant declaration \<open>c :: \<sigma>\<close> together with an axiom \<open>\<turnstile> c \<equiv> t\<close>, where \<open>t
   6.736 -  :: \<sigma>\<close> is a closed term without any hidden polymorphism.  The RHS
   6.737 -  may depend on further defined constants, but not \<open>c\<close> itself.
   6.738 -  Definitions of functions may be presented as \<open>c \<^vec>x \<equiv>
   6.739 -  t\<close> instead of the puristic \<open>c \<equiv> \<lambda>\<^vec>x. t\<close>.
   6.740 +  A \<^emph>\<open>simple definition\<close> consists of a constant declaration \<open>c :: \<sigma>\<close> together
   6.741 +  with an axiom \<open>\<turnstile> c \<equiv> t\<close>, where \<open>t :: \<sigma>\<close> is a closed term without any hidden
   6.742 +  polymorphism. The RHS may depend on further defined constants, but not \<open>c\<close>
   6.743 +  itself. Definitions of functions may be presented as \<open>c \<^vec>x \<equiv> t\<close>
   6.744 +  instead of the puristic \<open>c \<equiv> \<lambda>\<^vec>x. t\<close>.
   6.745  
   6.746 -  An \<^emph>\<open>overloaded definition\<close> consists of a collection of axioms
   6.747 -  for the same constant, with zero or one equations \<open>c((\<^vec>\<alpha>)\<kappa>) \<equiv> t\<close> for each type constructor \<open>\<kappa>\<close> (for
   6.748 -  distinct variables \<open>\<^vec>\<alpha>\<close>).  The RHS may mention
   6.749 -  previously defined constants as above, or arbitrary constants \<open>d(\<alpha>\<^sub>i)\<close> for some \<open>\<alpha>\<^sub>i\<close> projected from \<open>\<^vec>\<alpha>\<close>.  Thus overloaded definitions essentially work by
   6.750 -  primitive recursion over the syntactic structure of a single type
   6.751 -  argument.  See also @{cite \<open>\S4.3\<close> "Haftmann-Wenzel:2006:classes"}.
   6.752 +  An \<^emph>\<open>overloaded definition\<close> consists of a collection of axioms for the same
   6.753 +  constant, with zero or one equations \<open>c((\<^vec>\<alpha>)\<kappa>) \<equiv> t\<close> for each type
   6.754 +  constructor \<open>\<kappa>\<close> (for distinct variables \<open>\<^vec>\<alpha>\<close>). The RHS may mention
   6.755 +  previously defined constants as above, or arbitrary constants \<open>d(\<alpha>\<^sub>i)\<close> for
   6.756 +  some \<open>\<alpha>\<^sub>i\<close> projected from \<open>\<^vec>\<alpha>\<close>. Thus overloaded definitions
   6.757 +  essentially work by primitive recursion over the syntactic structure of a
   6.758 +  single type argument. See also @{cite \<open>\S4.3\<close>
   6.759 +  "Haftmann-Wenzel:2006:classes"}.
   6.760  \<close>
   6.761  
   6.762  text %mlref \<open>
   6.763 @@ -635,101 +601,89 @@
   6.764    Defs.entry -> Defs.entry list -> theory -> theory"} \\
   6.765    \end{mldecls}
   6.766  
   6.767 -  \<^descr> @{ML Thm.peek_status}~\<open>thm\<close> informs about the current
   6.768 -  status of the derivation object behind the given theorem.  This is a
   6.769 -  snapshot of a potentially ongoing (parallel) evaluation of proofs.
   6.770 -  The three Boolean values indicate the following: \<^verbatim>\<open>oracle\<close>
   6.771 -  if the finished part contains some oracle invocation; \<^verbatim>\<open>unfinished\<close>
   6.772 -  if some future proofs are still pending; \<^verbatim>\<open>failed\<close> if some future
   6.773 -  proof has failed, rendering the theorem invalid!
   6.774 +  \<^descr> @{ML Thm.peek_status}~\<open>thm\<close> informs about the current status of the
   6.775 +  derivation object behind the given theorem. This is a snapshot of a
   6.776 +  potentially ongoing (parallel) evaluation of proofs. The three Boolean
   6.777 +  values indicate the following: \<^verbatim>\<open>oracle\<close> if the finished part contains some
   6.778 +  oracle invocation; \<^verbatim>\<open>unfinished\<close> if some future proofs are still pending;
   6.779 +  \<^verbatim>\<open>failed\<close> if some future proof has failed, rendering the theorem invalid!
   6.780  
   6.781 -  \<^descr> @{ML Logic.all}~\<open>a B\<close> produces a Pure quantification
   6.782 -  \<open>\<And>a. B\<close>, where occurrences of the atomic term \<open>a\<close> in
   6.783 -  the body proposition \<open>B\<close> are replaced by bound variables.
   6.784 -  (See also @{ML lambda} on terms.)
   6.785 +  \<^descr> @{ML Logic.all}~\<open>a B\<close> produces a Pure quantification \<open>\<And>a. B\<close>, where
   6.786 +  occurrences of the atomic term \<open>a\<close> in the body proposition \<open>B\<close> are replaced
   6.787 +  by bound variables. (See also @{ML lambda} on terms.)
   6.788  
   6.789 -  \<^descr> @{ML Logic.mk_implies}~\<open>(A, B)\<close> produces a Pure
   6.790 -  implication \<open>A \<Longrightarrow> B\<close>.
   6.791 +  \<^descr> @{ML Logic.mk_implies}~\<open>(A, B)\<close> produces a Pure implication \<open>A \<Longrightarrow> B\<close>.
   6.792  
   6.793 -  \<^descr> Types @{ML_type ctyp} and @{ML_type cterm} represent certified
   6.794 -  types and terms, respectively.  These are abstract datatypes that
   6.795 -  guarantee that its values have passed the full well-formedness (and
   6.796 -  well-typedness) checks, relative to the declarations of type
   6.797 -  constructors, constants etc.\ in the background theory.  The
   6.798 -  abstract types @{ML_type ctyp} and @{ML_type cterm} are part of the
   6.799 -  same inference kernel that is mainly responsible for @{ML_type thm}.
   6.800 -  Thus syntactic operations on @{ML_type ctyp} and @{ML_type cterm}
   6.801 -  are located in the @{ML_structure Thm} module, even though theorems are
   6.802 -  not yet involved at that stage.
   6.803 +  \<^descr> Types @{ML_type ctyp} and @{ML_type cterm} represent certified types and
   6.804 +  terms, respectively. These are abstract datatypes that guarantee that its
   6.805 +  values have passed the full well-formedness (and well-typedness) checks,
   6.806 +  relative to the declarations of type constructors, constants etc.\ in the
   6.807 +  background theory. The abstract types @{ML_type ctyp} and @{ML_type cterm}
   6.808 +  are part of the same inference kernel that is mainly responsible for
   6.809 +  @{ML_type thm}. Thus syntactic operations on @{ML_type ctyp} and @{ML_type
   6.810 +  cterm} are located in the @{ML_structure Thm} module, even though theorems
   6.811 +  are not yet involved at that stage.
   6.812  
   6.813 -  \<^descr> @{ML Thm.ctyp_of}~\<open>ctxt \<tau>\<close> and @{ML
   6.814 -  Thm.cterm_of}~\<open>ctxt t\<close> explicitly check types and terms,
   6.815 -  respectively.  This also involves some basic normalizations, such
   6.816 -  expansion of type and term abbreviations from the underlying
   6.817 -  theory context.
   6.818 -  Full re-certification is relatively slow and should be avoided in
   6.819 -  tight reasoning loops.
   6.820 +  \<^descr> @{ML Thm.ctyp_of}~\<open>ctxt \<tau>\<close> and @{ML Thm.cterm_of}~\<open>ctxt t\<close> explicitly
   6.821 +  check types and terms, respectively. This also involves some basic
   6.822 +  normalizations, such expansion of type and term abbreviations from the
   6.823 +  underlying theory context. Full re-certification is relatively slow and
   6.824 +  should be avoided in tight reasoning loops.
   6.825  
   6.826 -  \<^descr> @{ML Thm.apply}, @{ML Thm.lambda}, @{ML Thm.all}, @{ML
   6.827 -  Drule.mk_implies} etc.\ compose certified terms (or propositions)
   6.828 -  incrementally.  This is equivalent to @{ML Thm.cterm_of} after
   6.829 -  unchecked @{ML_op "$"}, @{ML lambda}, @{ML Logic.all}, @{ML
   6.830 -  Logic.mk_implies} etc., but there can be a big difference in
   6.831 -  performance when large existing entities are composed by a few extra
   6.832 -  constructions on top.  There are separate operations to decompose
   6.833 +  \<^descr> @{ML Thm.apply}, @{ML Thm.lambda}, @{ML Thm.all}, @{ML Drule.mk_implies}
   6.834 +  etc.\ compose certified terms (or propositions) incrementally. This is
   6.835 +  equivalent to @{ML Thm.cterm_of} after unchecked @{ML_op "$"}, @{ML lambda},
   6.836 +  @{ML Logic.all}, @{ML Logic.mk_implies} etc., but there can be a big
   6.837 +  difference in performance when large existing entities are composed by a few
   6.838 +  extra constructions on top. There are separate operations to decompose
   6.839    certified terms and theorems to produce certified terms again.
   6.840  
   6.841 -  \<^descr> Type @{ML_type thm} represents proven propositions.  This is
   6.842 -  an abstract datatype that guarantees that its values have been
   6.843 -  constructed by basic principles of the @{ML_structure Thm} module.
   6.844 -  Every @{ML_type thm} value refers its background theory,
   6.845 -  cf.\ \secref{sec:context-theory}.
   6.846 +  \<^descr> Type @{ML_type thm} represents proven propositions. This is an abstract
   6.847 +  datatype that guarantees that its values have been constructed by basic
   6.848 +  principles of the @{ML_structure Thm} module. Every @{ML_type thm} value
   6.849 +  refers its background theory, cf.\ \secref{sec:context-theory}.
   6.850  
   6.851 -  \<^descr> @{ML Thm.transfer}~\<open>thy thm\<close> transfers the given
   6.852 -  theorem to a \<^emph>\<open>larger\<close> theory, see also \secref{sec:context}.
   6.853 -  This formal adjustment of the background context has no logical
   6.854 -  significance, but is occasionally required for formal reasons, e.g.\
   6.855 -  when theorems that are imported from more basic theories are used in
   6.856 -  the current situation.
   6.857 +  \<^descr> @{ML Thm.transfer}~\<open>thy thm\<close> transfers the given theorem to a \<^emph>\<open>larger\<close>
   6.858 +  theory, see also \secref{sec:context}. This formal adjustment of the
   6.859 +  background context has no logical significance, but is occasionally required
   6.860 +  for formal reasons, e.g.\ when theorems that are imported from more basic
   6.861 +  theories are used in the current situation.
   6.862  
   6.863 -  \<^descr> @{ML Thm.assume}, @{ML Thm.forall_intr}, @{ML
   6.864 -  Thm.forall_elim}, @{ML Thm.implies_intr}, and @{ML Thm.implies_elim}
   6.865 -  correspond to the primitive inferences of \figref{fig:prim-rules}.
   6.866 +  \<^descr> @{ML Thm.assume}, @{ML Thm.forall_intr}, @{ML Thm.forall_elim}, @{ML
   6.867 +  Thm.implies_intr}, and @{ML Thm.implies_elim} correspond to the primitive
   6.868 +  inferences of \figref{fig:prim-rules}.
   6.869  
   6.870 -  \<^descr> @{ML Thm.generalize}~\<open>(\<^vec>\<alpha>, \<^vec>x)\<close>
   6.871 -  corresponds to the \<open>generalize\<close> rules of
   6.872 -  \figref{fig:subst-rules}.  Here collections of type and term
   6.873 -  variables are generalized simultaneously, specified by the given
   6.874 -  basic names.
   6.875 +  \<^descr> @{ML Thm.generalize}~\<open>(\<^vec>\<alpha>, \<^vec>x)\<close> corresponds to the
   6.876 +  \<open>generalize\<close> rules of \figref{fig:subst-rules}. Here collections of type and
   6.877 +  term variables are generalized simultaneously, specified by the given basic
   6.878 +  names.
   6.879  
   6.880 -  \<^descr> @{ML Thm.instantiate}~\<open>(\<^vec>\<alpha>\<^sub>s,
   6.881 -  \<^vec>x\<^sub>\<tau>)\<close> corresponds to the \<open>instantiate\<close> rules
   6.882 -  of \figref{fig:subst-rules}.  Type variables are substituted before
   6.883 -  term variables.  Note that the types in \<open>\<^vec>x\<^sub>\<tau>\<close>
   6.884 -  refer to the instantiated versions.
   6.885 +  \<^descr> @{ML Thm.instantiate}~\<open>(\<^vec>\<alpha>\<^sub>s, \<^vec>x\<^sub>\<tau>)\<close> corresponds to the
   6.886 +  \<open>instantiate\<close> rules of \figref{fig:subst-rules}. Type variables are
   6.887 +  substituted before term variables. Note that the types in \<open>\<^vec>x\<^sub>\<tau>\<close> refer
   6.888 +  to the instantiated versions.
   6.889  
   6.890 -  \<^descr> @{ML Thm.add_axiom}~\<open>ctxt (name, A)\<close> declares an
   6.891 -  arbitrary proposition as axiom, and retrieves it as a theorem from
   6.892 -  the resulting theory, cf.\ \<open>axiom\<close> in
   6.893 -  \figref{fig:prim-rules}.  Note that the low-level representation in
   6.894 -  the axiom table may differ slightly from the returned theorem.
   6.895 +  \<^descr> @{ML Thm.add_axiom}~\<open>ctxt (name, A)\<close> declares an arbitrary proposition as
   6.896 +  axiom, and retrieves it as a theorem from the resulting theory, cf.\ \<open>axiom\<close>
   6.897 +  in \figref{fig:prim-rules}. Note that the low-level representation in the
   6.898 +  axiom table may differ slightly from the returned theorem.
   6.899  
   6.900 -  \<^descr> @{ML Thm.add_oracle}~\<open>(binding, oracle)\<close> produces a named
   6.901 -  oracle rule, essentially generating arbitrary axioms on the fly,
   6.902 -  cf.\ \<open>axiom\<close> in \figref{fig:prim-rules}.
   6.903 +  \<^descr> @{ML Thm.add_oracle}~\<open>(binding, oracle)\<close> produces a named oracle rule,
   6.904 +  essentially generating arbitrary axioms on the fly, cf.\ \<open>axiom\<close> in
   6.905 +  \figref{fig:prim-rules}.
   6.906  
   6.907 -  \<^descr> @{ML Thm.add_def}~\<open>ctxt unchecked overloaded (name, c
   6.908 -  \<^vec>x \<equiv> t)\<close> states a definitional axiom for an existing constant
   6.909 -  \<open>c\<close>.  Dependencies are recorded via @{ML Theory.add_deps},
   6.910 -  unless the \<open>unchecked\<close> option is set.  Note that the
   6.911 -  low-level representation in the axiom table may differ slightly from
   6.912 -  the returned theorem.
   6.913 +  \<^descr> @{ML Thm.add_def}~\<open>ctxt unchecked overloaded (name, c \<^vec>x \<equiv> t)\<close>
   6.914 +  states a definitional axiom for an existing constant \<open>c\<close>. Dependencies are
   6.915 +  recorded via @{ML Theory.add_deps}, unless the \<open>unchecked\<close> option is set.
   6.916 +  Note that the low-level representation in the axiom table may differ
   6.917 +  slightly from the returned theorem.
   6.918  
   6.919 -  \<^descr> @{ML Theory.add_deps}~\<open>ctxt name c\<^sub>\<tau> \<^vec>d\<^sub>\<sigma>\<close>
   6.920 -  declares dependencies of a named specification for constant \<open>c\<^sub>\<tau>\<close>, relative to existing specifications for constants \<open>\<^vec>d\<^sub>\<sigma>\<close>.  This also works for type constructors.
   6.921 +  \<^descr> @{ML Theory.add_deps}~\<open>ctxt name c\<^sub>\<tau> \<^vec>d\<^sub>\<sigma>\<close> declares dependencies of
   6.922 +  a named specification for constant \<open>c\<^sub>\<tau>\<close>, relative to existing
   6.923 +  specifications for constants \<open>\<^vec>d\<^sub>\<sigma>\<close>. This also works for type
   6.924 +  constructors.
   6.925  \<close>
   6.926  
   6.927 -
   6.928  text %mlantiq \<open>
   6.929    \begin{matharray}{rcl}
   6.930    @{ML_antiquotation_def "ctyp"} & : & \<open>ML_antiquotation\<close> \\
   6.931 @@ -755,46 +709,42 @@
   6.932      @'by' method method?
   6.933    \<close>}
   6.934  
   6.935 -  \<^descr> \<open>@{ctyp \<tau>}\<close> produces a certified type wrt.\ the
   6.936 -  current background theory --- as abstract value of type @{ML_type
   6.937 -  ctyp}.
   6.938 +  \<^descr> \<open>@{ctyp \<tau>}\<close> produces a certified type wrt.\ the current background theory
   6.939 +  --- as abstract value of type @{ML_type ctyp}.
   6.940 +
   6.941 +  \<^descr> \<open>@{cterm t}\<close> and \<open>@{cprop \<phi>}\<close> produce a certified term wrt.\ the current
   6.942 +  background theory --- as abstract value of type @{ML_type cterm}.
   6.943  
   6.944 -  \<^descr> \<open>@{cterm t}\<close> and \<open>@{cprop \<phi>}\<close> produce a
   6.945 -  certified term wrt.\ the current background theory --- as abstract
   6.946 -  value of type @{ML_type cterm}.
   6.947 +  \<^descr> \<open>@{thm a}\<close> produces a singleton fact --- as abstract value of type
   6.948 +  @{ML_type thm}.
   6.949  
   6.950 -  \<^descr> \<open>@{thm a}\<close> produces a singleton fact --- as abstract
   6.951 -  value of type @{ML_type thm}.
   6.952 -
   6.953 -  \<^descr> \<open>@{thms a}\<close> produces a general fact --- as abstract
   6.954 -  value of type @{ML_type "thm list"}.
   6.955 +  \<^descr> \<open>@{thms a}\<close> produces a general fact --- as abstract value of type
   6.956 +  @{ML_type "thm list"}.
   6.957  
   6.958 -  \<^descr> \<open>@{lemma \<phi> by meth}\<close> produces a fact that is proven on
   6.959 -  the spot according to the minimal proof, which imitates a terminal
   6.960 -  Isar proof.  The result is an abstract value of type @{ML_type thm}
   6.961 -  or @{ML_type "thm list"}, depending on the number of propositions
   6.962 -  given here.
   6.963 +  \<^descr> \<open>@{lemma \<phi> by meth}\<close> produces a fact that is proven on the spot according
   6.964 +  to the minimal proof, which imitates a terminal Isar proof. The result is an
   6.965 +  abstract value of type @{ML_type thm} or @{ML_type "thm list"}, depending on
   6.966 +  the number of propositions given here.
   6.967  
   6.968 -  The internal derivation object lacks a proper theorem name, but it
   6.969 -  is formally closed, unless the \<open>(open)\<close> option is specified
   6.970 -  (this may impact performance of applications with proof terms).
   6.971 +  The internal derivation object lacks a proper theorem name, but it is
   6.972 +  formally closed, unless the \<open>(open)\<close> option is specified (this may impact
   6.973 +  performance of applications with proof terms).
   6.974  
   6.975 -  Since ML antiquotations are always evaluated at compile-time, there
   6.976 -  is no run-time overhead even for non-trivial proofs.  Nonetheless,
   6.977 -  the justification is syntactically limited to a single @{command
   6.978 -  "by"} step.  More complex Isar proofs should be done in regular
   6.979 -  theory source, before compiling the corresponding ML text that uses
   6.980 -  the result.
   6.981 +  Since ML antiquotations are always evaluated at compile-time, there is no
   6.982 +  run-time overhead even for non-trivial proofs. Nonetheless, the
   6.983 +  justification is syntactically limited to a single @{command "by"} step.
   6.984 +  More complex Isar proofs should be done in regular theory source, before
   6.985 +  compiling the corresponding ML text that uses the result.
   6.986  \<close>
   6.987  
   6.988  
   6.989  subsection \<open>Auxiliary connectives \label{sec:logic-aux}\<close>
   6.990  
   6.991 -text \<open>Theory \<open>Pure\<close> provides a few auxiliary connectives
   6.992 -  that are defined on top of the primitive ones, see
   6.993 -  \figref{fig:pure-aux}.  These special constants are useful in
   6.994 -  certain internal encodings, and are normally not directly exposed to
   6.995 -  the user.
   6.996 +text \<open>
   6.997 +  Theory \<open>Pure\<close> provides a few auxiliary connectives that are defined on top
   6.998 +  of the primitive ones, see \figref{fig:pure-aux}. These special constants
   6.999 +  are useful in certain internal encodings, and are normally not directly
  6.1000 +  exposed to the user.
  6.1001  
  6.1002    \begin{figure}[htb]
  6.1003    \begin{center}
  6.1004 @@ -812,37 +762,32 @@
  6.1005    \end{center}
  6.1006    \end{figure}
  6.1007  
  6.1008 -  The introduction \<open>A \<Longrightarrow> B \<Longrightarrow> A &&& B\<close>, and eliminations
  6.1009 -  (projections) \<open>A &&& B \<Longrightarrow> A\<close> and \<open>A &&& B \<Longrightarrow> B\<close> are
  6.1010 -  available as derived rules.  Conjunction allows to treat
  6.1011 -  simultaneous assumptions and conclusions uniformly, e.g.\ consider
  6.1012 -  \<open>A \<Longrightarrow> B \<Longrightarrow> C &&& D\<close>.  In particular, the goal mechanism
  6.1013 -  represents multiple claims as explicit conjunction internally, but
  6.1014 -  this is refined (via backwards introduction) into separate sub-goals
  6.1015 -  before the user commences the proof; the final result is projected
  6.1016 -  into a list of theorems using eliminations (cf.\
  6.1017 -  \secref{sec:tactical-goals}).
  6.1018 +  The introduction \<open>A \<Longrightarrow> B \<Longrightarrow> A &&& B\<close>, and eliminations (projections) \<open>A &&& B
  6.1019 +  \<Longrightarrow> A\<close> and \<open>A &&& B \<Longrightarrow> B\<close> are available as derived rules. Conjunction allows to
  6.1020 +  treat simultaneous assumptions and conclusions uniformly, e.g.\ consider \<open>A
  6.1021 +  \<Longrightarrow> B \<Longrightarrow> C &&& D\<close>. In particular, the goal mechanism represents multiple claims
  6.1022 +  as explicit conjunction internally, but this is refined (via backwards
  6.1023 +  introduction) into separate sub-goals before the user commences the proof;
  6.1024 +  the final result is projected into a list of theorems using eliminations
  6.1025 +  (cf.\ \secref{sec:tactical-goals}).
  6.1026  
  6.1027 -  The \<open>prop\<close> marker (\<open>#\<close>) makes arbitrarily complex
  6.1028 -  propositions appear as atomic, without changing the meaning: \<open>\<Gamma> \<turnstile> A\<close> and \<open>\<Gamma> \<turnstile> #A\<close> are interchangeable.  See
  6.1029 -  \secref{sec:tactical-goals} for specific operations.
  6.1030 +  The \<open>prop\<close> marker (\<open>#\<close>) makes arbitrarily complex propositions appear as
  6.1031 +  atomic, without changing the meaning: \<open>\<Gamma> \<turnstile> A\<close> and \<open>\<Gamma> \<turnstile> #A\<close> are
  6.1032 +  interchangeable. See \secref{sec:tactical-goals} for specific operations.
  6.1033  
  6.1034 -  The \<open>term\<close> marker turns any well-typed term into a derivable
  6.1035 -  proposition: \<open>\<turnstile> TERM t\<close> holds unconditionally.  Although
  6.1036 -  this is logically vacuous, it allows to treat terms and proofs
  6.1037 -  uniformly, similar to a type-theoretic framework.
  6.1038 +  The \<open>term\<close> marker turns any well-typed term into a derivable proposition: \<open>\<turnstile>
  6.1039 +  TERM t\<close> holds unconditionally. Although this is logically vacuous, it allows
  6.1040 +  to treat terms and proofs uniformly, similar to a type-theoretic framework.
  6.1041  
  6.1042 -  The \<open>TYPE\<close> constructor is the canonical representative of
  6.1043 -  the unspecified type \<open>\<alpha> itself\<close>; it essentially injects the
  6.1044 -  language of types into that of terms.  There is specific notation
  6.1045 -  \<open>TYPE(\<tau>)\<close> for \<open>TYPE\<^bsub>\<tau> itself\<^esub>\<close>.
  6.1046 -  Although being devoid of any particular meaning, the term \<open>TYPE(\<tau>)\<close> accounts for the type \<open>\<tau>\<close> within the term
  6.1047 -  language.  In particular, \<open>TYPE(\<alpha>)\<close> may be used as formal
  6.1048 -  argument in primitive definitions, in order to circumvent hidden
  6.1049 -  polymorphism (cf.\ \secref{sec:terms}).  For example, \<open>c
  6.1050 -  TYPE(\<alpha>) \<equiv> A[\<alpha>]\<close> defines \<open>c :: \<alpha> itself \<Rightarrow> prop\<close> in terms of
  6.1051 -  a proposition \<open>A\<close> that depends on an additional type
  6.1052 -  argument, which is essentially a predicate on types.
  6.1053 +  The \<open>TYPE\<close> constructor is the canonical representative of the unspecified
  6.1054 +  type \<open>\<alpha> itself\<close>; it essentially injects the language of types into that of
  6.1055 +  terms. There is specific notation \<open>TYPE(\<tau>)\<close> for \<open>TYPE\<^bsub>\<tau> itself\<^esub>\<close>. Although
  6.1056 +  being devoid of any particular meaning, the term \<open>TYPE(\<tau>)\<close> accounts for the
  6.1057 +  type \<open>\<tau>\<close> within the term language. In particular, \<open>TYPE(\<alpha>)\<close> may be used as
  6.1058 +  formal argument in primitive definitions, in order to circumvent hidden
  6.1059 +  polymorphism (cf.\ \secref{sec:terms}). For example, \<open>c TYPE(\<alpha>) \<equiv> A[\<alpha>]\<close>
  6.1060 +  defines \<open>c :: \<alpha> itself \<Rightarrow> prop\<close> in terms of a proposition \<open>A\<close> that depends on
  6.1061 +  an additional type argument, which is essentially a predicate on types.
  6.1062  \<close>
  6.1063  
  6.1064  text %mlref \<open>
  6.1065 @@ -857,8 +802,7 @@
  6.1066  
  6.1067    \<^descr> @{ML Conjunction.intr} derives \<open>A &&& B\<close> from \<open>A\<close> and \<open>B\<close>.
  6.1068  
  6.1069 -  \<^descr> @{ML Conjunction.elim} derives \<open>A\<close> and \<open>B\<close>
  6.1070 -  from \<open>A &&& B\<close>.
  6.1071 +  \<^descr> @{ML Conjunction.elim} derives \<open>A\<close> and \<open>B\<close> from \<open>A &&& B\<close>.
  6.1072  
  6.1073    \<^descr> @{ML Drule.mk_term} derives \<open>TERM t\<close>.
  6.1074  
  6.1075 @@ -866,35 +810,35 @@
  6.1076  
  6.1077    \<^descr> @{ML Logic.mk_type}~\<open>\<tau>\<close> produces the term \<open>TYPE(\<tau>)\<close>.
  6.1078  
  6.1079 -  \<^descr> @{ML Logic.dest_type}~\<open>TYPE(\<tau>)\<close> recovers the type
  6.1080 -  \<open>\<tau>\<close>.
  6.1081 +  \<^descr> @{ML Logic.dest_type}~\<open>TYPE(\<tau>)\<close> recovers the type \<open>\<tau>\<close>.
  6.1082  \<close>
  6.1083  
  6.1084  
  6.1085  subsection \<open>Sort hypotheses\<close>
  6.1086  
  6.1087 -text \<open>Type variables are decorated with sorts, as explained in
  6.1088 -  \secref{sec:types}.  This constrains type instantiation to certain
  6.1089 -  ranges of types: variable \<open>\<alpha>\<^sub>s\<close> may only be assigned to types
  6.1090 -  \<open>\<tau>\<close> that belong to sort \<open>s\<close>.  Within the logic, sort
  6.1091 -  constraints act like implicit preconditions on the result \<open>\<lparr>\<alpha>\<^sub>1 : s\<^sub>1\<rparr>, \<dots>, \<lparr>\<alpha>\<^sub>n : s\<^sub>n\<rparr>, \<Gamma> \<turnstile> \<phi>\<close> where the type variables \<open>\<alpha>\<^sub>1, \<dots>, \<alpha>\<^sub>n\<close> cover the propositions \<open>\<Gamma>\<close>, \<open>\<phi>\<close>, as
  6.1092 -  well as the proof of \<open>\<Gamma> \<turnstile> \<phi>\<close>.
  6.1093 +text \<open>
  6.1094 +  Type variables are decorated with sorts, as explained in \secref{sec:types}.
  6.1095 +  This constrains type instantiation to certain ranges of types: variable
  6.1096 +  \<open>\<alpha>\<^sub>s\<close> may only be assigned to types \<open>\<tau>\<close> that belong to sort \<open>s\<close>. Within the
  6.1097 +  logic, sort constraints act like implicit preconditions on the result \<open>\<lparr>\<alpha>\<^sub>1
  6.1098 +  : s\<^sub>1\<rparr>, \<dots>, \<lparr>\<alpha>\<^sub>n : s\<^sub>n\<rparr>, \<Gamma> \<turnstile> \<phi>\<close> where the type variables \<open>\<alpha>\<^sub>1, \<dots>, \<alpha>\<^sub>n\<close> cover
  6.1099 +  the propositions \<open>\<Gamma>\<close>, \<open>\<phi>\<close>, as well as the proof of \<open>\<Gamma> \<turnstile> \<phi>\<close>.
  6.1100  
  6.1101 -  These \<^emph>\<open>sort hypothesis\<close> of a theorem are passed monotonically
  6.1102 -  through further derivations.  They are redundant, as long as the
  6.1103 -  statement of a theorem still contains the type variables that are
  6.1104 -  accounted here.  The logical significance of sort hypotheses is
  6.1105 -  limited to the boundary case where type variables disappear from the
  6.1106 -  proposition, e.g.\ \<open>\<lparr>\<alpha>\<^sub>s : s\<rparr> \<turnstile> \<phi>\<close>.  Since such dangling type
  6.1107 -  variables can be renamed arbitrarily without changing the
  6.1108 -  proposition \<open>\<phi>\<close>, the inference kernel maintains sort
  6.1109 -  hypotheses in anonymous form \<open>s \<turnstile> \<phi>\<close>.
  6.1110 +  These \<^emph>\<open>sort hypothesis\<close> of a theorem are passed monotonically through
  6.1111 +  further derivations. They are redundant, as long as the statement of a
  6.1112 +  theorem still contains the type variables that are accounted here. The
  6.1113 +  logical significance of sort hypotheses is limited to the boundary case
  6.1114 +  where type variables disappear from the proposition, e.g.\ \<open>\<lparr>\<alpha>\<^sub>s : s\<rparr> \<turnstile> \<phi>\<close>.
  6.1115 +  Since such dangling type variables can be renamed arbitrarily without
  6.1116 +  changing the proposition \<open>\<phi>\<close>, the inference kernel maintains sort hypotheses
  6.1117 +  in anonymous form \<open>s \<turnstile> \<phi>\<close>.
  6.1118  
  6.1119 -  In most practical situations, such extra sort hypotheses may be
  6.1120 -  stripped in a final bookkeeping step, e.g.\ at the end of a proof:
  6.1121 -  they are typically left over from intermediate reasoning with type
  6.1122 -  classes that can be satisfied by some concrete type \<open>\<tau>\<close> of
  6.1123 -  sort \<open>s\<close> to replace the hypothetical type variable \<open>\<alpha>\<^sub>s\<close>.\<close>
  6.1124 +  In most practical situations, such extra sort hypotheses may be stripped in
  6.1125 +  a final bookkeeping step, e.g.\ at the end of a proof: they are typically
  6.1126 +  left over from intermediate reasoning with type classes that can be
  6.1127 +  satisfied by some concrete type \<open>\<tau>\<close> of sort \<open>s\<close> to replace the hypothetical
  6.1128 +  type variable \<open>\<alpha>\<^sub>s\<close>.
  6.1129 +\<close>
  6.1130  
  6.1131  text %mlref \<open>
  6.1132    \begin{mldecls}
  6.1133 @@ -902,17 +846,18 @@
  6.1134    @{index_ML Thm.strip_shyps: "thm -> thm"} \\
  6.1135    \end{mldecls}
  6.1136  
  6.1137 -  \<^descr> @{ML Thm.extra_shyps}~\<open>thm\<close> determines the extraneous
  6.1138 -  sort hypotheses of the given theorem, i.e.\ the sorts that are not
  6.1139 -  present within type variables of the statement.
  6.1140 +  \<^descr> @{ML Thm.extra_shyps}~\<open>thm\<close> determines the extraneous sort hypotheses of
  6.1141 +  the given theorem, i.e.\ the sorts that are not present within type
  6.1142 +  variables of the statement.
  6.1143  
  6.1144 -  \<^descr> @{ML Thm.strip_shyps}~\<open>thm\<close> removes any extraneous
  6.1145 -  sort hypotheses that can be witnessed from the type signature.
  6.1146 +  \<^descr> @{ML Thm.strip_shyps}~\<open>thm\<close> removes any extraneous sort hypotheses that
  6.1147 +  can be witnessed from the type signature.
  6.1148  \<close>
  6.1149  
  6.1150 -text %mlex \<open>The following artificial example demonstrates the
  6.1151 -  derivation of @{prop False} with a pending sort hypothesis involving
  6.1152 -  a logically empty sort.\<close>
  6.1153 +text %mlex \<open>
  6.1154 +  The following artificial example demonstrates the derivation of @{prop
  6.1155 +  False} with a pending sort hypothesis involving a logically empty sort.
  6.1156 +\<close>
  6.1157  
  6.1158  class empty =
  6.1159    assumes bad: "\<And>(x::'a) y. x \<noteq> y"
  6.1160 @@ -922,55 +867,54 @@
  6.1161  
  6.1162  ML_val \<open>@{assert} (Thm.extra_shyps @{thm false} = [@{sort empty}])\<close>
  6.1163  
  6.1164 -text \<open>Thanks to the inference kernel managing sort hypothesis
  6.1165 -  according to their logical significance, this example is merely an
  6.1166 -  instance of \<^emph>\<open>ex falso quodlibet consequitur\<close> --- not a collapse
  6.1167 -  of the logical framework!\<close>
  6.1168 +text \<open>
  6.1169 +  Thanks to the inference kernel managing sort hypothesis according to their
  6.1170 +  logical significance, this example is merely an instance of \<^emph>\<open>ex falso
  6.1171 +  quodlibet consequitur\<close> --- not a collapse of the logical framework!
  6.1172 +\<close>
  6.1173  
  6.1174  
  6.1175  section \<open>Object-level rules \label{sec:obj-rules}\<close>
  6.1176  
  6.1177  text \<open>
  6.1178 -  The primitive inferences covered so far mostly serve foundational
  6.1179 -  purposes.  User-level reasoning usually works via object-level rules
  6.1180 -  that are represented as theorems of Pure.  Composition of rules
  6.1181 -  involves \<^emph>\<open>backchaining\<close>, \<^emph>\<open>higher-order unification\<close> modulo
  6.1182 -  \<open>\<alpha>\<beta>\<eta>\<close>-conversion of \<open>\<lambda>\<close>-terms, and so-called
  6.1183 -  \<^emph>\<open>lifting\<close> of rules into a context of \<open>\<And>\<close> and \<open>\<Longrightarrow>\<close> connectives.  Thus the full power of higher-order Natural
  6.1184 -  Deduction in Isabelle/Pure becomes readily available.
  6.1185 +  The primitive inferences covered so far mostly serve foundational purposes.
  6.1186 +  User-level reasoning usually works via object-level rules that are
  6.1187 +  represented as theorems of Pure. Composition of rules involves
  6.1188 +  \<^emph>\<open>backchaining\<close>, \<^emph>\<open>higher-order unification\<close> modulo \<open>\<alpha>\<beta>\<eta>\<close>-conversion of
  6.1189 +  \<open>\<lambda>\<close>-terms, and so-called \<^emph>\<open>lifting\<close> of rules into a context of \<open>\<And>\<close> and \<open>\<Longrightarrow>\<close>
  6.1190 +  connectives. Thus the full power of higher-order Natural Deduction in
  6.1191 +  Isabelle/Pure becomes readily available.
  6.1192  \<close>
  6.1193  
  6.1194  
  6.1195  subsection \<open>Hereditary Harrop Formulae\<close>
  6.1196  
  6.1197  text \<open>
  6.1198 -  The idea of object-level rules is to model Natural Deduction
  6.1199 -  inferences in the style of Gentzen @{cite "Gentzen:1935"}, but we allow
  6.1200 -  arbitrary nesting similar to @{cite extensions91}.  The most basic
  6.1201 -  rule format is that of a \<^emph>\<open>Horn Clause\<close>:
  6.1202 +  The idea of object-level rules is to model Natural Deduction inferences in
  6.1203 +  the style of Gentzen @{cite "Gentzen:1935"}, but we allow arbitrary nesting
  6.1204 +  similar to @{cite extensions91}. The most basic rule format is that of a
  6.1205 +  \<^emph>\<open>Horn Clause\<close>:
  6.1206    \[
  6.1207    \infer{\<open>A\<close>}{\<open>A\<^sub>1\<close> & \<open>\<dots>\<close> & \<open>A\<^sub>n\<close>}
  6.1208    \]
  6.1209 -  where \<open>A, A\<^sub>1, \<dots>, A\<^sub>n\<close> are atomic propositions
  6.1210 -  of the framework, usually of the form \<open>Trueprop B\<close>, where
  6.1211 -  \<open>B\<close> is a (compound) object-level statement.  This
  6.1212 -  object-level inference corresponds to an iterated implication in
  6.1213 -  Pure like this:
  6.1214 +  where \<open>A, A\<^sub>1, \<dots>, A\<^sub>n\<close> are atomic propositions of the framework, usually of
  6.1215 +  the form \<open>Trueprop B\<close>, where \<open>B\<close> is a (compound) object-level statement.
  6.1216 +  This object-level inference corresponds to an iterated implication in Pure
  6.1217 +  like this:
  6.1218    \[
  6.1219    \<open>A\<^sub>1 \<Longrightarrow> \<dots> A\<^sub>n \<Longrightarrow> A\<close>
  6.1220    \]
  6.1221 -  As an example consider conjunction introduction: \<open>A \<Longrightarrow> B \<Longrightarrow> A \<and>
  6.1222 -  B\<close>.  Any parameters occurring in such rule statements are
  6.1223 -  conceptionally treated as arbitrary:
  6.1224 +  As an example consider conjunction introduction: \<open>A \<Longrightarrow> B \<Longrightarrow> A \<and> B\<close>. Any
  6.1225 +  parameters occurring in such rule statements are conceptionally treated as
  6.1226 +  arbitrary:
  6.1227    \[
  6.1228    \<open>\<And>x\<^sub>1 \<dots> x\<^sub>m. A\<^sub>1 x\<^sub>1 \<dots> x\<^sub>m \<Longrightarrow> \<dots> A\<^sub>n x\<^sub>1 \<dots> x\<^sub>m \<Longrightarrow> A x\<^sub>1 \<dots> x\<^sub>m\<close>
  6.1229    \]
  6.1230  
  6.1231 -  Nesting of rules means that the positions of \<open>A\<^sub>i\<close> may
  6.1232 -  again hold compound rules, not just atomic propositions.
  6.1233 -  Propositions of this format are called \<^emph>\<open>Hereditary Harrop
  6.1234 -  Formulae\<close> in the literature @{cite "Miller:1991"}.  Here we give an
  6.1235 -  inductive characterization as follows:
  6.1236 +  Nesting of rules means that the positions of \<open>A\<^sub>i\<close> may again hold compound
  6.1237 +  rules, not just atomic propositions. Propositions of this format are called
  6.1238 +  \<^emph>\<open>Hereditary Harrop Formulae\<close> in the literature @{cite "Miller:1991"}. Here
  6.1239 +  we give an inductive characterization as follows:
  6.1240  
  6.1241    \<^medskip>
  6.1242    \begin{tabular}{ll}
  6.1243 @@ -980,29 +924,26 @@
  6.1244    \end{tabular}
  6.1245    \<^medskip>
  6.1246  
  6.1247 -  Thus we essentially impose nesting levels on propositions formed
  6.1248 -  from \<open>\<And>\<close> and \<open>\<Longrightarrow>\<close>.  At each level there is a prefix
  6.1249 -  of parameters and compound premises, concluding an atomic
  6.1250 -  proposition.  Typical examples are \<open>\<longrightarrow>\<close>-introduction \<open>(A \<Longrightarrow> B) \<Longrightarrow> A \<longrightarrow> B\<close> or mathematical induction \<open>P 0 \<Longrightarrow> (\<And>n. P n
  6.1251 -  \<Longrightarrow> P (Suc n)) \<Longrightarrow> P n\<close>.  Even deeper nesting occurs in well-founded
  6.1252 -  induction \<open>(\<And>x. (\<And>y. y \<prec> x \<Longrightarrow> P y) \<Longrightarrow> P x) \<Longrightarrow> P x\<close>, but this
  6.1253 -  already marks the limit of rule complexity that is usually seen in
  6.1254 -  practice.
  6.1255 +  Thus we essentially impose nesting levels on propositions formed from \<open>\<And>\<close>
  6.1256 +  and \<open>\<Longrightarrow>\<close>. At each level there is a prefix of parameters and compound
  6.1257 +  premises, concluding an atomic proposition. Typical examples are
  6.1258 +  \<open>\<longrightarrow>\<close>-introduction \<open>(A \<Longrightarrow> B) \<Longrightarrow> A \<longrightarrow> B\<close> or mathematical induction \<open>P 0 \<Longrightarrow> (\<And>n. P n
  6.1259 +  \<Longrightarrow> P (Suc n)) \<Longrightarrow> P n\<close>. Even deeper nesting occurs in well-founded induction
  6.1260 +  \<open>(\<And>x. (\<And>y. y \<prec> x \<Longrightarrow> P y) \<Longrightarrow> P x) \<Longrightarrow> P x\<close>, but this already marks the limit of
  6.1261 +  rule complexity that is usually seen in practice.
  6.1262  
  6.1263    \<^medskip>
  6.1264 -  Regular user-level inferences in Isabelle/Pure always
  6.1265 -  maintain the following canonical form of results:
  6.1266 +  Regular user-level inferences in Isabelle/Pure always maintain the following
  6.1267 +  canonical form of results:
  6.1268  
  6.1269 -  \<^item> Normalization by \<open>(A \<Longrightarrow> (\<And>x. B x)) \<equiv> (\<And>x. A \<Longrightarrow> B x)\<close>,
  6.1270 -  which is a theorem of Pure, means that quantifiers are pushed in
  6.1271 -  front of implication at each level of nesting.  The normal form is a
  6.1272 -  Hereditary Harrop Formula.
  6.1273 +  \<^item> Normalization by \<open>(A \<Longrightarrow> (\<And>x. B x)) \<equiv> (\<And>x. A \<Longrightarrow> B x)\<close>, which is a theorem of
  6.1274 +  Pure, means that quantifiers are pushed in front of implication at each
  6.1275 +  level of nesting. The normal form is a Hereditary Harrop Formula.
  6.1276  
  6.1277 -  \<^item> The outermost prefix of parameters is represented via
  6.1278 -  schematic variables: instead of \<open>\<And>\<^vec>x. \<^vec>H \<^vec>x
  6.1279 -  \<Longrightarrow> A \<^vec>x\<close> we have \<open>\<^vec>H ?\<^vec>x \<Longrightarrow> A ?\<^vec>x\<close>.
  6.1280 -  Note that this representation looses information about the order of
  6.1281 -  parameters, and vacuous quantifiers vanish automatically.
  6.1282 +  \<^item> The outermost prefix of parameters is represented via schematic variables:
  6.1283 +  instead of \<open>\<And>\<^vec>x. \<^vec>H \<^vec>x \<Longrightarrow> A \<^vec>x\<close> we have \<open>\<^vec>H
  6.1284 +  ?\<^vec>x \<Longrightarrow> A ?\<^vec>x\<close>. Note that this representation looses information
  6.1285 +  about the order of parameters, and vacuous quantifiers vanish automatically.
  6.1286  \<close>
  6.1287  
  6.1288  text %mlref \<open>
  6.1289 @@ -1010,43 +951,42 @@
  6.1290    @{index_ML Simplifier.norm_hhf: "Proof.context -> thm -> thm"} \\
  6.1291    \end{mldecls}
  6.1292  
  6.1293 -  \<^descr> @{ML Simplifier.norm_hhf}~\<open>ctxt thm\<close> normalizes the given
  6.1294 -  theorem according to the canonical form specified above.  This is
  6.1295 -  occasionally helpful to repair some low-level tools that do not
  6.1296 -  handle Hereditary Harrop Formulae properly.
  6.1297 +  \<^descr> @{ML Simplifier.norm_hhf}~\<open>ctxt thm\<close> normalizes the given theorem
  6.1298 +  according to the canonical form specified above. This is occasionally
  6.1299 +  helpful to repair some low-level tools that do not handle Hereditary Harrop
  6.1300 +  Formulae properly.
  6.1301  \<close>
  6.1302  
  6.1303  
  6.1304  subsection \<open>Rule composition\<close>
  6.1305  
  6.1306  text \<open>
  6.1307 -  The rule calculus of Isabelle/Pure provides two main inferences:
  6.1308 -  @{inference resolution} (i.e.\ back-chaining of rules) and
  6.1309 -  @{inference assumption} (i.e.\ closing a branch), both modulo
  6.1310 -  higher-order unification.  There are also combined variants, notably
  6.1311 -  @{inference elim_resolution} and @{inference dest_resolution}.
  6.1312 +  The rule calculus of Isabelle/Pure provides two main inferences: @{inference
  6.1313 +  resolution} (i.e.\ back-chaining of rules) and @{inference assumption}
  6.1314 +  (i.e.\ closing a branch), both modulo higher-order unification. There are
  6.1315 +  also combined variants, notably @{inference elim_resolution} and @{inference
  6.1316 +  dest_resolution}.
  6.1317  
  6.1318 -  To understand the all-important @{inference resolution} principle,
  6.1319 -  we first consider raw @{inference_def composition} (modulo
  6.1320 -  higher-order unification with substitution \<open>\<vartheta>\<close>):
  6.1321 +  To understand the all-important @{inference resolution} principle, we first
  6.1322 +  consider raw @{inference_def composition} (modulo higher-order unification
  6.1323 +  with substitution \<open>\<vartheta>\<close>):
  6.1324    \[
  6.1325    \infer[(@{inference_def composition})]{\<open>\<^vec>A\<vartheta> \<Longrightarrow> C\<vartheta>\<close>}
  6.1326    {\<open>\<^vec>A \<Longrightarrow> B\<close> & \<open>B' \<Longrightarrow> C\<close> & \<open>B\<vartheta> = B'\<vartheta>\<close>}
  6.1327    \]
  6.1328 -  Here the conclusion of the first rule is unified with the premise of
  6.1329 -  the second; the resulting rule instance inherits the premises of the
  6.1330 -  first and conclusion of the second.  Note that \<open>C\<close> can again
  6.1331 -  consist of iterated implications.  We can also permute the premises
  6.1332 -  of the second rule back-and-forth in order to compose with \<open>B'\<close> in any position (subsequently we shall always refer to
  6.1333 -  position 1 w.l.o.g.).
  6.1334 +  Here the conclusion of the first rule is unified with the premise of the
  6.1335 +  second; the resulting rule instance inherits the premises of the first and
  6.1336 +  conclusion of the second. Note that \<open>C\<close> can again consist of iterated
  6.1337 +  implications. We can also permute the premises of the second rule
  6.1338 +  back-and-forth in order to compose with \<open>B'\<close> in any position (subsequently
  6.1339 +  we shall always refer to position 1 w.l.o.g.).
  6.1340  
  6.1341 -  In @{inference composition} the internal structure of the common
  6.1342 -  part \<open>B\<close> and \<open>B'\<close> is not taken into account.  For
  6.1343 -  proper @{inference resolution} we require \<open>B\<close> to be atomic,
  6.1344 -  and explicitly observe the structure \<open>\<And>\<^vec>x. \<^vec>H
  6.1345 -  \<^vec>x \<Longrightarrow> B' \<^vec>x\<close> of the premise of the second rule.  The
  6.1346 -  idea is to adapt the first rule by ``lifting'' it into this context,
  6.1347 -  by means of iterated application of the following inferences:
  6.1348 +  In @{inference composition} the internal structure of the common part \<open>B\<close>
  6.1349 +  and \<open>B'\<close> is not taken into account. For proper @{inference resolution} we
  6.1350 +  require \<open>B\<close> to be atomic, and explicitly observe the structure \<open>\<And>\<^vec>x.
  6.1351 +  \<^vec>H \<^vec>x \<Longrightarrow> B' \<^vec>x\<close> of the premise of the second rule. The idea
  6.1352 +  is to adapt the first rule by ``lifting'' it into this context, by means of
  6.1353 +  iterated application of the following inferences:
  6.1354    \[
  6.1355    \infer[(@{inference_def imp_lift})]{\<open>(\<^vec>H \<Longrightarrow> \<^vec>A) \<Longrightarrow> (\<^vec>H \<Longrightarrow> B)\<close>}{\<open>\<^vec>A \<Longrightarrow> B\<close>}
  6.1356    \]
  6.1357 @@ -1065,10 +1005,10 @@
  6.1358     \end{tabular}}
  6.1359    \]
  6.1360  
  6.1361 -  Continued resolution of rules allows to back-chain a problem towards
  6.1362 -  more and sub-problems.  Branches are closed either by resolving with
  6.1363 -  a rule of 0 premises, or by producing a ``short-circuit'' within a
  6.1364 -  solved situation (again modulo unification):
  6.1365 +  Continued resolution of rules allows to back-chain a problem towards more
  6.1366 +  and sub-problems. Branches are closed either by resolving with a rule of 0
  6.1367 +  premises, or by producing a ``short-circuit'' within a solved situation
  6.1368 +  (again modulo unification):
  6.1369    \[
  6.1370    \infer[(@{inference_def assumption})]{\<open>C\<vartheta>\<close>}
  6.1371    {\<open>(\<And>\<^vec>x. \<^vec>H \<^vec>x \<Longrightarrow> A \<^vec>x) \<Longrightarrow> C\<close> & \<open>A\<vartheta> = H\<^sub>i\<vartheta>\<close>~~\text{(for some~\<open>i\<close>)}}
  6.1372 @@ -1089,133 +1029,125 @@
  6.1373    @{index_ML_op "OF": "thm * thm list -> thm"} \\
  6.1374    \end{mldecls}
  6.1375  
  6.1376 -  \<^descr> \<open>rule\<^sub>1 RSN (i, rule\<^sub>2)\<close> resolves the conclusion of
  6.1377 -  \<open>rule\<^sub>1\<close> with the \<open>i\<close>-th premise of \<open>rule\<^sub>2\<close>,
  6.1378 -  according to the @{inference resolution} principle explained above.
  6.1379 -  Unless there is precisely one resolvent it raises exception @{ML
  6.1380 -  THM}.
  6.1381 +  \<^descr> \<open>rule\<^sub>1 RSN (i, rule\<^sub>2)\<close> resolves the conclusion of \<open>rule\<^sub>1\<close> with the
  6.1382 +  \<open>i\<close>-th premise of \<open>rule\<^sub>2\<close>, according to the @{inference resolution}
  6.1383 +  principle explained above. Unless there is precisely one resolvent it raises
  6.1384 +  exception @{ML THM}.
  6.1385  
  6.1386 -  This corresponds to the rule attribute @{attribute THEN} in Isar
  6.1387 -  source language.
  6.1388 +  This corresponds to the rule attribute @{attribute THEN} in Isar source
  6.1389 +  language.
  6.1390  
  6.1391 -  \<^descr> \<open>rule\<^sub>1 RS rule\<^sub>2\<close> abbreviates \<open>rule\<^sub>1 RSN (1,
  6.1392 -  rule\<^sub>2)\<close>.
  6.1393 +  \<^descr> \<open>rule\<^sub>1 RS rule\<^sub>2\<close> abbreviates \<open>rule\<^sub>1 RSN (1, rule\<^sub>2)\<close>.
  6.1394  
  6.1395 -  \<^descr> \<open>rules\<^sub>1 RLN (i, rules\<^sub>2)\<close> joins lists of rules.  For
  6.1396 -  every \<open>rule\<^sub>1\<close> in \<open>rules\<^sub>1\<close> and \<open>rule\<^sub>2\<close> in
  6.1397 -  \<open>rules\<^sub>2\<close>, it resolves the conclusion of \<open>rule\<^sub>1\<close> with
  6.1398 -  the \<open>i\<close>-th premise of \<open>rule\<^sub>2\<close>, accumulating multiple
  6.1399 -  results in one big list.  Note that such strict enumerations of
  6.1400 -  higher-order unifications can be inefficient compared to the lazy
  6.1401 -  variant seen in elementary tactics like @{ML resolve_tac}.
  6.1402 +  \<^descr> \<open>rules\<^sub>1 RLN (i, rules\<^sub>2)\<close> joins lists of rules. For every \<open>rule\<^sub>1\<close> in
  6.1403 +  \<open>rules\<^sub>1\<close> and \<open>rule\<^sub>2\<close> in \<open>rules\<^sub>2\<close>, it resolves the conclusion of \<open>rule\<^sub>1\<close>
  6.1404 +  with the \<open>i\<close>-th premise of \<open>rule\<^sub>2\<close>, accumulating multiple results in one
  6.1405 +  big list. Note that such strict enumerations of higher-order unifications
  6.1406 +  can be inefficient compared to the lazy variant seen in elementary tactics
  6.1407 +  like @{ML resolve_tac}.
  6.1408  
  6.1409 -  \<^descr> \<open>rules\<^sub>1 RL rules\<^sub>2\<close> abbreviates \<open>rules\<^sub>1 RLN (1,
  6.1410 -  rules\<^sub>2)\<close>.
  6.1411 +  \<^descr> \<open>rules\<^sub>1 RL rules\<^sub>2\<close> abbreviates \<open>rules\<^sub>1 RLN (1, rules\<^sub>2)\<close>.
  6.1412  
  6.1413 -  \<^descr> \<open>[rule\<^sub>1, \<dots>, rule\<^sub>n] MRS rule\<close> resolves \<open>rule\<^sub>i\<close>
  6.1414 -  against premise \<open>i\<close> of \<open>rule\<close>, for \<open>i = n, \<dots>,
  6.1415 -  1\<close>.  By working from right to left, newly emerging premises are
  6.1416 -  concatenated in the result, without interfering.
  6.1417 +  \<^descr> \<open>[rule\<^sub>1, \<dots>, rule\<^sub>n] MRS rule\<close> resolves \<open>rule\<^sub>i\<close> against premise \<open>i\<close> of
  6.1418 +  \<open>rule\<close>, for \<open>i = n, \<dots>, 1\<close>. By working from right to left, newly emerging
  6.1419 +  premises are concatenated in the result, without interfering.
  6.1420  
  6.1421 -  \<^descr> \<open>rule OF rules\<close> is an alternative notation for \<open>rules MRS rule\<close>, which makes rule composition look more like
  6.1422 -  function application.  Note that the argument \<open>rules\<close> need
  6.1423 -  not be atomic.
  6.1424 +  \<^descr> \<open>rule OF rules\<close> is an alternative notation for \<open>rules MRS rule\<close>, which
  6.1425 +  makes rule composition look more like function application. Note that the
  6.1426 +  argument \<open>rules\<close> need not be atomic.
  6.1427  
  6.1428 -  This corresponds to the rule attribute @{attribute OF} in Isar
  6.1429 -  source language.
  6.1430 +  This corresponds to the rule attribute @{attribute OF} in Isar source
  6.1431 +  language.
  6.1432  \<close>
  6.1433  
  6.1434  
  6.1435  section \<open>Proof terms \label{sec:proof-terms}\<close>
  6.1436  
  6.1437 -text \<open>The Isabelle/Pure inference kernel can record the proof of
  6.1438 -  each theorem as a proof term that contains all logical inferences in
  6.1439 -  detail.  Rule composition by resolution (\secref{sec:obj-rules}) and
  6.1440 -  type-class reasoning is broken down to primitive rules of the
  6.1441 -  logical framework.  The proof term can be inspected by a separate
  6.1442 -  proof-checker, for example.
  6.1443 +text \<open>
  6.1444 +  The Isabelle/Pure inference kernel can record the proof of each theorem as a
  6.1445 +  proof term that contains all logical inferences in detail. Rule composition
  6.1446 +  by resolution (\secref{sec:obj-rules}) and type-class reasoning is broken
  6.1447 +  down to primitive rules of the logical framework. The proof term can be
  6.1448 +  inspected by a separate proof-checker, for example.
  6.1449  
  6.1450 -  According to the well-known \<^emph>\<open>Curry-Howard isomorphism\<close>, a proof
  6.1451 -  can be viewed as a \<open>\<lambda>\<close>-term. Following this idea, proofs in
  6.1452 -  Isabelle are internally represented by a datatype similar to the one
  6.1453 -  for terms described in \secref{sec:terms}.  On top of these
  6.1454 -  syntactic terms, two more layers of \<open>\<lambda>\<close>-calculus are added,
  6.1455 -  which correspond to \<open>\<And>x :: \<alpha>. B x\<close> and \<open>A \<Longrightarrow> B\<close>
  6.1456 -  according to the propositions-as-types principle.  The resulting
  6.1457 -  3-level \<open>\<lambda>\<close>-calculus resembles ``\<open>\<lambda>HOL\<close>'' in the
  6.1458 -  more abstract setting of Pure Type Systems (PTS)
  6.1459 -  @{cite "Barendregt-Geuvers:2001"}, if some fine points like schematic
  6.1460 -  polymorphism and type classes are ignored.
  6.1461 +  According to the well-known \<^emph>\<open>Curry-Howard isomorphism\<close>, a proof can be
  6.1462 +  viewed as a \<open>\<lambda>\<close>-term. Following this idea, proofs in Isabelle are internally
  6.1463 +  represented by a datatype similar to the one for terms described in
  6.1464 +  \secref{sec:terms}. On top of these syntactic terms, two more layers of
  6.1465 +  \<open>\<lambda>\<close>-calculus are added, which correspond to \<open>\<And>x :: \<alpha>. B x\<close> and \<open>A \<Longrightarrow> B\<close>
  6.1466 +  according to the propositions-as-types principle. The resulting 3-level
  6.1467 +  \<open>\<lambda>\<close>-calculus resembles ``\<open>\<lambda>HOL\<close>'' in the more abstract setting of Pure Type
  6.1468 +  Systems (PTS) @{cite "Barendregt-Geuvers:2001"}, if some fine points like
  6.1469 +  schematic polymorphism and type classes are ignored.
  6.1470  
  6.1471    \<^medskip>
  6.1472 -  \<^emph>\<open>Proof abstractions\<close> of the form \<open>\<^bold>\<lambda>x :: \<alpha>. prf\<close>
  6.1473 -  or \<open>\<^bold>\<lambda>p : A. prf\<close> correspond to introduction of \<open>\<And>\<close>/\<open>\<Longrightarrow>\<close>, and \<^emph>\<open>proof applications\<close> of the form \<open>p \<cdot> t\<close> or \<open>p \<bullet> q\<close> correspond to elimination of \<open>\<And>\<close>/\<open>\<Longrightarrow>\<close>.  Actual types \<open>\<alpha>\<close>, propositions \<open>A\<close>, and terms \<open>t\<close> might be suppressed and reconstructed
  6.1474 -  from the overall proof term.
  6.1475 +  \<^emph>\<open>Proof abstractions\<close> of the form \<open>\<^bold>\<lambda>x :: \<alpha>. prf\<close> or \<open>\<^bold>\<lambda>p : A. prf\<close>
  6.1476 +  correspond to introduction of \<open>\<And>\<close>/\<open>\<Longrightarrow>\<close>, and \<^emph>\<open>proof applications\<close> of the form
  6.1477 +  \<open>p \<cdot> t\<close> or \<open>p \<bullet> q\<close> correspond to elimination of \<open>\<And>\<close>/\<open>\<Longrightarrow>\<close>. Actual types \<open>\<alpha>\<close>,
  6.1478 +  propositions \<open>A\<close>, and terms \<open>t\<close> might be suppressed and reconstructed from
  6.1479 +  the overall proof term.
  6.1480  
  6.1481    \<^medskip>
  6.1482 -  Various atomic proofs indicate special situations within
  6.1483 -  the proof construction as follows.
  6.1484 +  Various atomic proofs indicate special situations within the proof
  6.1485 +  construction as follows.
  6.1486  
  6.1487 -  A \<^emph>\<open>bound proof variable\<close> is a natural number \<open>b\<close> that
  6.1488 -  acts as de-Bruijn index for proof term abstractions.
  6.1489 +  A \<^emph>\<open>bound proof variable\<close> is a natural number \<open>b\<close> that acts as de-Bruijn
  6.1490 +  index for proof term abstractions.
  6.1491  
  6.1492 -  A \<^emph>\<open>minimal proof\<close> ``\<open>?\<close>'' is a dummy proof term.  This
  6.1493 -  indicates some unrecorded part of the proof.
  6.1494 +  A \<^emph>\<open>minimal proof\<close> ``\<open>?\<close>'' is a dummy proof term. This indicates some
  6.1495 +  unrecorded part of the proof.
  6.1496  
  6.1497 -  \<open>Hyp A\<close> refers to some pending hypothesis by giving its
  6.1498 -  proposition.  This indicates an open context of implicit hypotheses,
  6.1499 -  similar to loose bound variables or free variables within a term
  6.1500 -  (\secref{sec:terms}).
  6.1501 +  \<open>Hyp A\<close> refers to some pending hypothesis by giving its proposition. This
  6.1502 +  indicates an open context of implicit hypotheses, similar to loose bound
  6.1503 +  variables or free variables within a term (\secref{sec:terms}).
  6.1504  
  6.1505 -  An \<^emph>\<open>axiom\<close> or \<^emph>\<open>oracle\<close> \<open>a : A[\<^vec>\<tau>]\<close> refers
  6.1506 -  some postulated \<open>proof constant\<close>, which is subject to
  6.1507 -  schematic polymorphism of theory content, and the particular type
  6.1508 -  instantiation may be given explicitly.  The vector of types \<open>\<^vec>\<tau>\<close> refers to the schematic type variables in the generic
  6.1509 +  An \<^emph>\<open>axiom\<close> or \<^emph>\<open>oracle\<close> \<open>a : A[\<^vec>\<tau>]\<close> refers some postulated \<open>proof
  6.1510 +  constant\<close>, which is subject to schematic polymorphism of theory content, and
  6.1511 +  the particular type instantiation may be given explicitly. The vector of
  6.1512 +  types \<open>\<^vec>\<tau>\<close> refers to the schematic type variables in the generic
  6.1513    proposition \<open>A\<close> in canonical order.
  6.1514  
  6.1515 -  A \<^emph>\<open>proof promise\<close> \<open>a : A[\<^vec>\<tau>]\<close> is a placeholder
  6.1516 -  for some proof of polymorphic proposition \<open>A\<close>, with explicit
  6.1517 -  type instantiation as given by the vector \<open>\<^vec>\<tau>\<close>, as
  6.1518 -  above.  Unlike axioms or oracles, proof promises may be
  6.1519 -  \<^emph>\<open>fulfilled\<close> eventually, by substituting \<open>a\<close> by some
  6.1520 -  particular proof \<open>q\<close> at the corresponding type instance.
  6.1521 -  This acts like Hindley-Milner \<open>let\<close>-polymorphism: a generic
  6.1522 -  local proof definition may get used at different type instances, and
  6.1523 -  is replaced by the concrete instance eventually.
  6.1524 +  A \<^emph>\<open>proof promise\<close> \<open>a : A[\<^vec>\<tau>]\<close> is a placeholder for some proof of
  6.1525 +  polymorphic proposition \<open>A\<close>, with explicit type instantiation as given by
  6.1526 +  the vector \<open>\<^vec>\<tau>\<close>, as above. Unlike axioms or oracles, proof promises
  6.1527 +  may be \<^emph>\<open>fulfilled\<close> eventually, by substituting \<open>a\<close> by some particular proof
  6.1528 +  \<open>q\<close> at the corresponding type instance. This acts like Hindley-Milner
  6.1529 +  \<open>let\<close>-polymorphism: a generic local proof definition may get used at
  6.1530 +  different type instances, and is replaced by the concrete instance
  6.1531 +  eventually.
  6.1532  
  6.1533 -  A \<^emph>\<open>named theorem\<close> wraps up some concrete proof as a closed
  6.1534 -  formal entity, in the manner of constant definitions for proof
  6.1535 -  terms.  The \<^emph>\<open>proof body\<close> of such boxed theorems involves some
  6.1536 -  digest about oracles and promises occurring in the original proof.
  6.1537 -  This allows the inference kernel to manage this critical information
  6.1538 -  without the full overhead of explicit proof terms.
  6.1539 +  A \<^emph>\<open>named theorem\<close> wraps up some concrete proof as a closed formal entity,
  6.1540 +  in the manner of constant definitions for proof terms. The \<^emph>\<open>proof body\<close> of
  6.1541 +  such boxed theorems involves some digest about oracles and promises
  6.1542 +  occurring in the original proof. This allows the inference kernel to manage
  6.1543 +  this critical information without the full overhead of explicit proof terms.
  6.1544  \<close>
  6.1545  
  6.1546  
  6.1547  subsection \<open>Reconstructing and checking proof terms\<close>
  6.1548  
  6.1549 -text \<open>Fully explicit proof terms can be large, but most of this
  6.1550 -  information is redundant and can be reconstructed from the context.
  6.1551 -  Therefore, the Isabelle/Pure inference kernel records only
  6.1552 -  \<^emph>\<open>implicit\<close> proof terms, by omitting all typing information in
  6.1553 -  terms, all term and type labels of proof abstractions, and some
  6.1554 -  argument terms of applications \<open>p \<cdot> t\<close> (if possible).
  6.1555 +text \<open>
  6.1556 +  Fully explicit proof terms can be large, but most of this information is
  6.1557 +  redundant and can be reconstructed from the context. Therefore, the
  6.1558 +  Isabelle/Pure inference kernel records only \<^emph>\<open>implicit\<close> proof terms, by
  6.1559 +  omitting all typing information in terms, all term and type labels of proof
  6.1560 +  abstractions, and some argument terms of applications \<open>p \<cdot> t\<close> (if possible).
  6.1561  
  6.1562 -  There are separate operations to reconstruct the full proof term
  6.1563 -  later on, using \<^emph>\<open>higher-order pattern unification\<close>
  6.1564 -  @{cite "nipkow-patterns" and "Berghofer-Nipkow:2000:TPHOL"}.
  6.1565 +  There are separate operations to reconstruct the full proof term later on,
  6.1566 +  using \<^emph>\<open>higher-order pattern unification\<close> @{cite "nipkow-patterns" and
  6.1567 +  "Berghofer-Nipkow:2000:TPHOL"}.
  6.1568  
  6.1569 -  The \<^emph>\<open>proof checker\<close> expects a fully reconstructed proof term,
  6.1570 -  and can turn it into a theorem by replaying its primitive inferences
  6.1571 -  within the kernel.\<close>
  6.1572 +  The \<^emph>\<open>proof checker\<close> expects a fully reconstructed proof term, and can turn
  6.1573 +  it into a theorem by replaying its primitive inferences within the kernel.
  6.1574 +\<close>
  6.1575  
  6.1576  
  6.1577  subsection \<open>Concrete syntax of proof terms\<close>
  6.1578  
  6.1579 -text \<open>The concrete syntax of proof terms is a slight extension of
  6.1580 -  the regular inner syntax of Isabelle/Pure @{cite "isabelle-isar-ref"}.
  6.1581 -  Its main syntactic category @{syntax (inner) proof} is defined as
  6.1582 -  follows:
  6.1583 +text \<open>
  6.1584 +  The concrete syntax of proof terms is a slight extension of the regular
  6.1585 +  inner syntax of Isabelle/Pure @{cite "isabelle-isar-ref"}. Its main
  6.1586 +  syntactic category @{syntax (inner) proof} is defined as follows:
  6.1587  
  6.1588    \begin{center}
  6.1589    \begin{supertabular}{rclr}
  6.1590 @@ -1240,13 +1172,14 @@
  6.1591    \end{supertabular}
  6.1592    \end{center}
  6.1593  
  6.1594 -  Implicit term arguments in partial proofs are indicated by ``\<open>_\<close>''.  Type arguments for theorems and axioms may be specified
  6.1595 -  using \<open>p \<cdot> TYPE(type)\<close> (they must appear before any other
  6.1596 -  term argument of a theorem or axiom, but may be omitted altogether).
  6.1597 +  Implicit term arguments in partial proofs are indicated by ``\<open>_\<close>''. Type
  6.1598 +  arguments for theorems and axioms may be specified using \<open>p \<cdot> TYPE(type)\<close>
  6.1599 +  (they must appear before any other term argument of a theorem or axiom, but
  6.1600 +  may be omitted altogether).
  6.1601  
  6.1602    \<^medskip>
  6.1603 -  There are separate read and print operations for proof
  6.1604 -  terms, in order to avoid conflicts with the regular term language.
  6.1605 +  There are separate read and print operations for proof terms, in order to
  6.1606 +  avoid conflicts with the regular term language.
  6.1607  \<close>
  6.1608  
  6.1609  text %mlref \<open>
  6.1610 @@ -1263,65 +1196,60 @@
  6.1611    @{index_ML Proof_Syntax.pretty_proof: "Proof.context -> proof -> Pretty.T"} \\
  6.1612    \end{mldecls}
  6.1613  
  6.1614 -  \<^descr> Type @{ML_type proof} represents proof terms; this is a
  6.1615 -  datatype with constructors @{index_ML Abst}, @{index_ML AbsP},
  6.1616 -  @{index_ML_op "%"}, @{index_ML_op "%%"}, @{index_ML PBound},
  6.1617 -  @{index_ML MinProof}, @{index_ML Hyp}, @{index_ML PAxm}, @{index_ML
  6.1618 -  Oracle}, @{index_ML Promise}, @{index_ML PThm} as explained above.
  6.1619 -  %FIXME OfClass (!?)
  6.1620 +  \<^descr> Type @{ML_type proof} represents proof terms; this is a datatype with
  6.1621 +  constructors @{index_ML Abst}, @{index_ML AbsP}, @{index_ML_op "%"},
  6.1622 +  @{index_ML_op "%%"}, @{index_ML PBound}, @{index_ML MinProof}, @{index_ML
  6.1623 +  Hyp}, @{index_ML PAxm}, @{index_ML Oracle}, @{index_ML Promise}, @{index_ML
  6.1624 +  PThm} as explained above. %FIXME OfClass (!?)
  6.1625 +
  6.1626 +  \<^descr> Type @{ML_type proof_body} represents the nested proof information of a
  6.1627 +  named theorem, consisting of a digest of oracles and named theorem over some
  6.1628 +  proof term. The digest only covers the directly visible part of the proof:
  6.1629 +  in order to get the full information, the implicit graph of nested theorems
  6.1630 +  needs to be traversed (e.g.\ using @{ML Proofterm.fold_body_thms}).
  6.1631  
  6.1632 -  \<^descr> Type @{ML_type proof_body} represents the nested proof
  6.1633 -  information of a named theorem, consisting of a digest of oracles
  6.1634 -  and named theorem over some proof term.  The digest only covers the
  6.1635 -  directly visible part of the proof: in order to get the full
  6.1636 -  information, the implicit graph of nested theorems needs to be
  6.1637 -  traversed (e.g.\ using @{ML Proofterm.fold_body_thms}).
  6.1638 +  \<^descr> @{ML Thm.proof_of}~\<open>thm\<close> and @{ML Thm.proof_body_of}~\<open>thm\<close> produce the
  6.1639 +  proof term or proof body (with digest of oracles and theorems) from a given
  6.1640 +  theorem. Note that this involves a full join of internal futures that
  6.1641 +  fulfill pending proof promises, and thus disrupts the natural bottom-up
  6.1642 +  construction of proofs by introducing dynamic ad-hoc dependencies. Parallel
  6.1643 +  performance may suffer by inspecting proof terms at run-time.
  6.1644  
  6.1645 -  \<^descr> @{ML Thm.proof_of}~\<open>thm\<close> and @{ML
  6.1646 -  Thm.proof_body_of}~\<open>thm\<close> produce the proof term or proof
  6.1647 -  body (with digest of oracles and theorems) from a given theorem.
  6.1648 -  Note that this involves a full join of internal futures that fulfill
  6.1649 -  pending proof promises, and thus disrupts the natural bottom-up
  6.1650 -  construction of proofs by introducing dynamic ad-hoc dependencies.
  6.1651 -  Parallel performance may suffer by inspecting proof terms at
  6.1652 -  run-time.
  6.1653 +  \<^descr> @{ML proofs} specifies the detail of proof recording within @{ML_type thm}
  6.1654 +  values produced by the inference kernel: @{ML 0} records only the names of
  6.1655 +  oracles, @{ML 1} records oracle names and propositions, @{ML 2} additionally
  6.1656 +  records full proof terms. Officially named theorems that contribute to a
  6.1657 +  result are recorded in any case.
  6.1658  
  6.1659 -  \<^descr> @{ML proofs} specifies the detail of proof recording within
  6.1660 -  @{ML_type thm} values produced by the inference kernel: @{ML 0}
  6.1661 -  records only the names of oracles, @{ML 1} records oracle names and
  6.1662 -  propositions, @{ML 2} additionally records full proof terms.
  6.1663 -  Officially named theorems that contribute to a result are recorded
  6.1664 -  in any case.
  6.1665 +  \<^descr> @{ML Reconstruct.reconstruct_proof}~\<open>thy prop prf\<close> turns the implicit
  6.1666 +  proof term \<open>prf\<close> into a full proof of the given proposition.
  6.1667  
  6.1668 -  \<^descr> @{ML Reconstruct.reconstruct_proof}~\<open>thy prop prf\<close>
  6.1669 -  turns the implicit proof term \<open>prf\<close> into a full proof of the
  6.1670 -  given proposition.
  6.1671 -
  6.1672 -  Reconstruction may fail if \<open>prf\<close> is not a proof of \<open>prop\<close>, or if it does not contain sufficient information for
  6.1673 -  reconstruction.  Failure may only happen for proofs that are
  6.1674 -  constructed manually, but not for those produced automatically by
  6.1675 -  the inference kernel.
  6.1676 +  Reconstruction may fail if \<open>prf\<close> is not a proof of \<open>prop\<close>, or if it does not
  6.1677 +  contain sufficient information for reconstruction. Failure may only happen
  6.1678 +  for proofs that are constructed manually, but not for those produced
  6.1679 +  automatically by the inference kernel.
  6.1680  
  6.1681 -  \<^descr> @{ML Reconstruct.expand_proof}~\<open>thy [thm\<^sub>1, \<dots>, thm\<^sub>n]
  6.1682 -  prf\<close> expands and reconstructs the proofs of all specified theorems,
  6.1683 -  with the given (full) proof.  Theorems that are not unique specified
  6.1684 -  via their name may be disambiguated by giving their proposition.
  6.1685 +  \<^descr> @{ML Reconstruct.expand_proof}~\<open>thy [thm\<^sub>1, \<dots>, thm\<^sub>n] prf\<close> expands and
  6.1686 +  reconstructs the proofs of all specified theorems, with the given (full)
  6.1687 +  proof. Theorems that are not unique specified via their name may be
  6.1688 +  disambiguated by giving their proposition.
  6.1689  
  6.1690 -  \<^descr> @{ML Proof_Checker.thm_of_proof}~\<open>thy prf\<close> turns the
  6.1691 -  given (full) proof into a theorem, by replaying it using only
  6.1692 -  primitive rules of the inference kernel.
  6.1693 +  \<^descr> @{ML Proof_Checker.thm_of_proof}~\<open>thy prf\<close> turns the given (full) proof
  6.1694 +  into a theorem, by replaying it using only primitive rules of the inference
  6.1695 +  kernel.
  6.1696  
  6.1697 -  \<^descr> @{ML Proof_Syntax.read_proof}~\<open>thy b\<^sub>1 b\<^sub>2 s\<close> reads in a
  6.1698 -  proof term. The Boolean flags indicate the use of sort and type
  6.1699 -  information.  Usually, typing information is left implicit and is
  6.1700 -  inferred during proof reconstruction.  %FIXME eliminate flags!?
  6.1701 +  \<^descr> @{ML Proof_Syntax.read_proof}~\<open>thy b\<^sub>1 b\<^sub>2 s\<close> reads in a proof term. The
  6.1702 +  Boolean flags indicate the use of sort and type information. Usually, typing
  6.1703 +  information is left implicit and is inferred during proof reconstruction.
  6.1704 +  %FIXME eliminate flags!?
  6.1705  
  6.1706 -  \<^descr> @{ML Proof_Syntax.pretty_proof}~\<open>ctxt prf\<close>
  6.1707 -  pretty-prints the given proof term.
  6.1708 +  \<^descr> @{ML Proof_Syntax.pretty_proof}~\<open>ctxt prf\<close> pretty-prints the given proof
  6.1709 +  term.
  6.1710  \<close>
  6.1711  
  6.1712 -text %mlex \<open>Detailed proof information of a theorem may be retrieved
  6.1713 -  as follows:\<close>
  6.1714 +text %mlex \<open>
  6.1715 +  Detailed proof information of a theorem may be retrieved as follows:
  6.1716 +\<close>
  6.1717  
  6.1718  lemma ex: "A \<and> B \<longrightarrow> B \<and> A"
  6.1719  proof
  6.1720 @@ -1344,15 +1272,16 @@
  6.1721        (fn (name, _, _) => insert (op =) name) [body] [];
  6.1722  \<close>
  6.1723  
  6.1724 -text \<open>The result refers to various basic facts of Isabelle/HOL:
  6.1725 -  @{thm [source] HOL.impI}, @{thm [source] HOL.conjE}, @{thm [source]
  6.1726 -  HOL.conjI} etc.  The combinator @{ML Proofterm.fold_body_thms}
  6.1727 -  recursively explores the graph of the proofs of all theorems being
  6.1728 -  used here.
  6.1729 +text \<open>
  6.1730 +  The result refers to various basic facts of Isabelle/HOL: @{thm [source]
  6.1731 +  HOL.impI}, @{thm [source] HOL.conjE}, @{thm [source] HOL.conjI} etc. The
  6.1732 +  combinator @{ML Proofterm.fold_body_thms} recursively explores the graph of
  6.1733 +  the proofs of all theorems being used here.
  6.1734  
  6.1735    \<^medskip>
  6.1736 -  Alternatively, we may produce a proof term manually, and
  6.1737 -  turn it into a theorem as follows:\<close>
  6.1738 +  Alternatively, we may produce a proof term manually, and turn it into a
  6.1739 +  theorem as follows:
  6.1740 +\<close>
  6.1741  
  6.1742  ML_val \<open>
  6.1743    val thy = @{theory};
  6.1744 @@ -1371,9 +1300,8 @@
  6.1745  
  6.1746  text \<open>
  6.1747    \<^medskip>
  6.1748 -  See also @{file "~~/src/HOL/Proofs/ex/XML_Data.thy"}
  6.1749 -  for further examples, with export and import of proof terms via
  6.1750 -  XML/ML data representation.
  6.1751 +  See also @{file "~~/src/HOL/Proofs/ex/XML_Data.thy"} for further examples,
  6.1752 +  with export and import of proof terms via XML/ML data representation.
  6.1753  \<close>
  6.1754  
  6.1755  end
     7.1 --- a/src/Doc/Implementation/ML.thy	Tue Dec 15 14:41:47 2015 +0000
     7.2 +++ b/src/Doc/Implementation/ML.thy	Wed Dec 16 17:30:30 2015 +0100
     7.3 @@ -6,75 +6,72 @@
     7.4  
     7.5  chapter \<open>Isabelle/ML\<close>
     7.6  
     7.7 -text \<open>Isabelle/ML is best understood as a certain culture based on
     7.8 -  Standard ML.  Thus it is not a new programming language, but a
     7.9 -  certain way to use SML at an advanced level within the Isabelle
    7.10 -  environment.  This covers a variety of aspects that are geared
    7.11 -  towards an efficient and robust platform for applications of formal
    7.12 -  logic with fully foundational proof construction --- according to
    7.13 -  the well-known \<^emph>\<open>LCF principle\<close>.  There is specific
    7.14 -  infrastructure with library modules to address the needs of this
    7.15 -  difficult task.  For example, the raw parallel programming model of
    7.16 -  Poly/ML is presented as considerably more abstract concept of
    7.17 -  \<^emph>\<open>futures\<close>, which is then used to augment the inference
    7.18 -  kernel, Isar theory and proof interpreter, and PIDE document management.
    7.19 +text \<open>
    7.20 +  Isabelle/ML is best understood as a certain culture based on Standard ML.
    7.21 +  Thus it is not a new programming language, but a certain way to use SML at
    7.22 +  an advanced level within the Isabelle environment. This covers a variety of
    7.23 +  aspects that are geared towards an efficient and robust platform for
    7.24 +  applications of formal logic with fully foundational proof construction ---
    7.25 +  according to the well-known \<^emph>\<open>LCF principle\<close>. There is specific
    7.26 +  infrastructure with library modules to address the needs of this difficult
    7.27 +  task. For example, the raw parallel programming model of Poly/ML is
    7.28 +  presented as considerably more abstract concept of \<^emph>\<open>futures\<close>, which is then
    7.29 +  used to augment the inference kernel, Isar theory and proof interpreter, and
    7.30 +  PIDE document management.
    7.31  
    7.32 -  The main aspects of Isabelle/ML are introduced below.  These
    7.33 -  first-hand explanations should help to understand how proper
    7.34 -  Isabelle/ML is to be read and written, and to get access to the
    7.35 -  wealth of experience that is expressed in the source text and its
    7.36 -  history of changes.\<^footnote>\<open>See
    7.37 -  @{url "http://isabelle.in.tum.de/repos/isabelle"} for the full
    7.38 -  Mercurial history.  There are symbolic tags to refer to official
    7.39 -  Isabelle releases, as opposed to arbitrary \<^emph>\<open>tip\<close> versions that
    7.40 -  merely reflect snapshots that are never really up-to-date.\<close>\<close>
    7.41 +  The main aspects of Isabelle/ML are introduced below. These first-hand
    7.42 +  explanations should help to understand how proper Isabelle/ML is to be read
    7.43 +  and written, and to get access to the wealth of experience that is expressed
    7.44 +  in the source text and its history of changes.\<^footnote>\<open>See @{url
    7.45 +  "http://isabelle.in.tum.de/repos/isabelle"} for the full Mercurial history.
    7.46 +  There are symbolic tags to refer to official Isabelle releases, as opposed
    7.47 +  to arbitrary \<^emph>\<open>tip\<close> versions that merely reflect snapshots that are never
    7.48 +  really up-to-date.\<close>
    7.49 +\<close>
    7.50  
    7.51  
    7.52  section \<open>Style and orthography\<close>
    7.53  
    7.54 -text \<open>The sources of Isabelle/Isar are optimized for
    7.55 -  \<^emph>\<open>readability\<close> and \<^emph>\<open>maintainability\<close>.  The main purpose is
    7.56 -  to tell an informed reader what is really going on and how things
    7.57 -  really work.  This is a non-trivial aim, but it is supported by a
    7.58 -  certain style of writing Isabelle/ML that has emerged from long
    7.59 -  years of system development.\<^footnote>\<open>See also the interesting style
    7.60 -  guide for OCaml
    7.61 -  @{url "http://caml.inria.fr/resources/doc/guides/guidelines.en.html"}
    7.62 -  which shares many of our means and ends.\<close>
    7.63 +text \<open>
    7.64 +  The sources of Isabelle/Isar are optimized for \<^emph>\<open>readability\<close> and
    7.65 +  \<^emph>\<open>maintainability\<close>. The main purpose is to tell an informed reader what is
    7.66 +  really going on and how things really work. This is a non-trivial aim, but
    7.67 +  it is supported by a certain style of writing Isabelle/ML that has emerged
    7.68 +  from long years of system development.\<^footnote>\<open>See also the interesting style guide
    7.69 +  for OCaml @{url
    7.70 +  "http://caml.inria.fr/resources/doc/guides/guidelines.en.html"} which shares
    7.71 +  many of our means and ends.\<close>
    7.72  
    7.73 -  The main principle behind any coding style is \<^emph>\<open>consistency\<close>.
    7.74 -  For a single author of a small program this merely means ``choose
    7.75 -  your style and stick to it''.  A complex project like Isabelle, with
    7.76 -  long years of development and different contributors, requires more
    7.77 -  standardization.  A coding style that is changed every few years or
    7.78 -  with every new contributor is no style at all, because consistency
    7.79 -  is quickly lost.  Global consistency is hard to achieve, though.
    7.80 -  Nonetheless, one should always strive at least for local consistency
    7.81 -  of modules and sub-systems, without deviating from some general
    7.82 -  principles how to write Isabelle/ML.
    7.83 +  The main principle behind any coding style is \<^emph>\<open>consistency\<close>. For a single
    7.84 +  author of a small program this merely means ``choose your style and stick to
    7.85 +  it''. A complex project like Isabelle, with long years of development and
    7.86 +  different contributors, requires more standardization. A coding style that
    7.87 +  is changed every few years or with every new contributor is no style at all,
    7.88 +  because consistency is quickly lost. Global consistency is hard to achieve,
    7.89 +  though. Nonetheless, one should always strive at least for local consistency
    7.90 +  of modules and sub-systems, without deviating from some general principles
    7.91 +  how to write Isabelle/ML.
    7.92  
    7.93 -  In a sense, good coding style is like an \<^emph>\<open>orthography\<close> for the
    7.94 -  sources: it helps to read quickly over the text and see through the
    7.95 -  main points, without getting distracted by accidental presentation
    7.96 -  of free-style code.
    7.97 +  In a sense, good coding style is like an \<^emph>\<open>orthography\<close> for the sources: it
    7.98 +  helps to read quickly over the text and see through the main points, without
    7.99 +  getting distracted by accidental presentation of free-style code.
   7.100  \<close>
   7.101  
   7.102  
   7.103  subsection \<open>Header and sectioning\<close>
   7.104  
   7.105 -text \<open>Isabelle source files have a certain standardized header
   7.106 -  format (with precise spacing) that follows ancient traditions
   7.107 -  reaching back to the earliest versions of the system by Larry
   7.108 -  Paulson.  See @{file "~~/src/Pure/thm.ML"}, for example.
   7.109 +text \<open>
   7.110 +  Isabelle source files have a certain standardized header format (with
   7.111 +  precise spacing) that follows ancient traditions reaching back to the
   7.112 +  earliest versions of the system by Larry Paulson. See @{file
   7.113 +  "~~/src/Pure/thm.ML"}, for example.
   7.114  
   7.115 -  The header includes at least \<^verbatim>\<open>Title\<close> and \<^verbatim>\<open>Author\<close> entries,
   7.116 -  followed by a prose description of the purpose of
   7.117 -  the module.  The latter can range from a single line to several
   7.118 -  paragraphs of explanations.
   7.119 +  The header includes at least \<^verbatim>\<open>Title\<close> and \<^verbatim>\<open>Author\<close> entries, followed by a
   7.120 +  prose description of the purpose of the module. The latter can range from a
   7.121 +  single line to several paragraphs of explanations.
   7.122  
   7.123 -  The rest of the file is divided into sections, subsections,
   7.124 -  subsubsections, paragraphs etc.\ using a simple layout via ML
   7.125 -  comments as follows.
   7.126 +  The rest of the file is divided into sections, subsections, subsubsections,
   7.127 +  paragraphs etc.\ using a simple layout via ML comments as follows.
   7.128  
   7.129    @{verbatim [display]
   7.130  \<open>  (*** section ***)
   7.131 @@ -90,26 +87,28 @@
   7.132      with more text
   7.133    *)\<close>}
   7.134  
   7.135 -  As in regular typography, there is some extra space \<^emph>\<open>before\<close>
   7.136 -  section headings that are adjacent to plain text, but not other headings
   7.137 -  as in the example above.
   7.138 +  As in regular typography, there is some extra space \<^emph>\<open>before\<close> section
   7.139 +  headings that are adjacent to plain text, but not other headings as in the
   7.140 +  example above.
   7.141  
   7.142    \<^medskip>
   7.143 -  The precise wording of the prose text given in these
   7.144 -  headings is chosen carefully to introduce the main theme of the
   7.145 -  subsequent formal ML text.
   7.146 +  The precise wording of the prose text given in these headings is chosen
   7.147 +  carefully to introduce the main theme of the subsequent formal ML text.
   7.148  \<close>
   7.149  
   7.150  
   7.151  subsection \<open>Naming conventions\<close>
   7.152  
   7.153 -text \<open>Since ML is the primary medium to express the meaning of the
   7.154 -  source text, naming of ML entities requires special care.\<close>
   7.155 +text \<open>
   7.156 +  Since ML is the primary medium to express the meaning of the source text,
   7.157 +  naming of ML entities requires special care.
   7.158 +\<close>
   7.159  
   7.160  paragraph \<open>Notation.\<close>
   7.161 -text \<open>A name consists of 1--3 \<^emph>\<open>words\<close> (rarely 4, but not more) that are
   7.162 -  separated by underscore. There are three variants concerning upper or lower
   7.163 -  case letters, which are used for certain ML categories as follows:
   7.164 +text \<open>
   7.165 +  A name consists of 1--3 \<^emph>\<open>words\<close> (rarely 4, but not more) that are separated
   7.166 +  by underscore. There are three variants concerning upper or lower case
   7.167 +  letters, which are used for certain ML categories as follows:
   7.168  
   7.169    \<^medskip>
   7.170    \begin{tabular}{lll}
   7.171 @@ -120,38 +119,37 @@
   7.172    \end{tabular}
   7.173    \<^medskip>
   7.174  
   7.175 -  For historical reasons, many capitalized names omit underscores,
   7.176 -  e.g.\ old-style @{ML_text FooBar} instead of @{ML_text Foo_Bar}.
   7.177 -  Genuine mixed-case names are \<^emph>\<open>not\<close> used, because clear division
   7.178 -  of words is essential for readability.\<^footnote>\<open>Camel-case was
   7.179 -  invented to workaround the lack of underscore in some early
   7.180 -  non-ASCII character sets.  Later it became habitual in some language
   7.181 -  communities that are now strong in numbers.\<close>
   7.182 +  For historical reasons, many capitalized names omit underscores, e.g.\
   7.183 +  old-style @{ML_text FooBar} instead of @{ML_text Foo_Bar}. Genuine
   7.184 +  mixed-case names are \<^emph>\<open>not\<close> used, because clear division of words is
   7.185 +  essential for readability.\<^footnote>\<open>Camel-case was invented to workaround the lack
   7.186 +  of underscore in some early non-ASCII character sets. Later it became
   7.187 +  habitual in some language communities that are now strong in numbers.\<close>
   7.188  
   7.189 -  A single (capital) character does not count as ``word'' in this
   7.190 -  respect: some Isabelle/ML names are suffixed by extra markers like
   7.191 -  this: @{ML_text foo_barT}.
   7.192 +  A single (capital) character does not count as ``word'' in this respect:
   7.193 +  some Isabelle/ML names are suffixed by extra markers like this: @{ML_text
   7.194 +  foo_barT}.
   7.195  
   7.196 -  Name variants are produced by adding 1--3 primes, e.g.\ @{ML_text
   7.197 -  foo'}, @{ML_text foo''}, or @{ML_text foo'''}, but not @{ML_text
   7.198 -  foo''''} or more.  Decimal digits scale better to larger numbers,
   7.199 -  e.g.\ @{ML_text foo0}, @{ML_text foo1}, @{ML_text foo42}.
   7.200 +  Name variants are produced by adding 1--3 primes, e.g.\ @{ML_text foo'},
   7.201 +  @{ML_text foo''}, or @{ML_text foo'''}, but not @{ML_text foo''''} or more.
   7.202 +  Decimal digits scale better to larger numbers, e.g.\ @{ML_text foo0},
   7.203 +  @{ML_text foo1}, @{ML_text foo42}.
   7.204  \<close>
   7.205  
   7.206  paragraph\<open>Scopes.\<close>
   7.207 -text \<open>Apart from very basic library modules, ML structures are not ``opened'',
   7.208 -  but names are referenced with explicit qualification, as in @{ML
   7.209 +text \<open>
   7.210 +  Apart from very basic library modules, ML structures are not ``opened'', but
   7.211 +  names are referenced with explicit qualification, as in @{ML
   7.212    Syntax.string_of_term} for example. When devising names for structures and
   7.213    their components it is important to aim at eye-catching compositions of both
   7.214    parts, because this is how they are seen in the sources and documentation.
   7.215    For the same reasons, aliases of well-known library functions should be
   7.216    avoided.
   7.217  
   7.218 -  Local names of function abstraction or case/let bindings are
   7.219 -  typically shorter, sometimes using only rudiments of ``words'',
   7.220 -  while still avoiding cryptic shorthands.  An auxiliary function
   7.221 -  called @{ML_text helper}, @{ML_text aux}, or @{ML_text f} is
   7.222 -  considered bad style.
   7.223 +  Local names of function abstraction or case/let bindings are typically
   7.224 +  shorter, sometimes using only rudiments of ``words'', while still avoiding
   7.225 +  cryptic shorthands. An auxiliary function called @{ML_text helper},
   7.226 +  @{ML_text aux}, or @{ML_text f} is considered bad style.
   7.227  
   7.228    Example:
   7.229  
   7.230 @@ -184,28 +182,28 @@
   7.231  \<close>
   7.232  
   7.233  paragraph \<open>Specific conventions.\<close>
   7.234 -text \<open>Here are some specific name forms that occur frequently in the sources.
   7.235 +text \<open>
   7.236 +  Here are some specific name forms that occur frequently in the sources.
   7.237  
   7.238 -  \<^item> A function that maps @{ML_text foo} to @{ML_text bar} is
   7.239 -  called @{ML_text foo_to_bar} or @{ML_text bar_of_foo} (never
   7.240 -  @{ML_text foo2bar}, nor @{ML_text bar_from_foo}, nor @{ML_text
   7.241 -  bar_for_foo}, nor @{ML_text bar4foo}).
   7.242 +  \<^item> A function that maps @{ML_text foo} to @{ML_text bar} is called @{ML_text
   7.243 +  foo_to_bar} or @{ML_text bar_of_foo} (never @{ML_text foo2bar}, nor
   7.244 +  @{ML_text bar_from_foo}, nor @{ML_text bar_for_foo}, nor @{ML_text
   7.245 +  bar4foo}).
   7.246  
   7.247 -  \<^item> The name component @{ML_text legacy} means that the operation
   7.248 -  is about to be discontinued soon.
   7.249 +  \<^item> The name component @{ML_text legacy} means that the operation is about to
   7.250 +  be discontinued soon.
   7.251  
   7.252 -  \<^item> The name component @{ML_text global} means that this works
   7.253 -  with the background theory instead of the regular local context
   7.254 -  (\secref{sec:context}), sometimes for historical reasons, sometimes
   7.255 -  due a genuine lack of locality of the concept involved, sometimes as
   7.256 -  a fall-back for the lack of a proper context in the application
   7.257 -  code.  Whenever there is a non-global variant available, the
   7.258 -  application should be migrated to use it with a proper local
   7.259 -  context.
   7.260 +  \<^item> The name component @{ML_text global} means that this works with the
   7.261 +  background theory instead of the regular local context
   7.262 +  (\secref{sec:context}), sometimes for historical reasons, sometimes due a
   7.263 +  genuine lack of locality of the concept involved, sometimes as a fall-back
   7.264 +  for the lack of a proper context in the application code. Whenever there is
   7.265 +  a non-global variant available, the application should be migrated to use it
   7.266 +  with a proper local context.
   7.267  
   7.268 -  \<^item> Variables of the main context types of the Isabelle/Isar
   7.269 -  framework (\secref{sec:context} and \chref{ch:local-theory}) have
   7.270 -  firm naming conventions as follows:
   7.271 +  \<^item> Variables of the main context types of the Isabelle/Isar framework
   7.272 +  (\secref{sec:context} and \chref{ch:local-theory}) have firm naming
   7.273 +  conventions as follows:
   7.274  
   7.275      \<^item> theories are called @{ML_text thy}, rarely @{ML_text theory}
   7.276      (never @{ML_text thry})
   7.277 @@ -219,54 +217,51 @@
   7.278      theories that are treated as proof context (which is a semantic
   7.279      super-type)
   7.280  
   7.281 -  Variations with primed or decimal numbers are always possible, as
   7.282 -  well as semantic prefixes like @{ML_text foo_thy} or @{ML_text
   7.283 -  bar_ctxt}, but the base conventions above need to be preserved.
   7.284 -  This allows to emphasize their data flow via plain regular
   7.285 -  expressions in the text editor.
   7.286 +  Variations with primed or decimal numbers are always possible, as well as
   7.287 +  semantic prefixes like @{ML_text foo_thy} or @{ML_text bar_ctxt}, but the
   7.288 +  base conventions above need to be preserved. This allows to emphasize their
   7.289 +  data flow via plain regular expressions in the text editor.
   7.290  
   7.291 -  \<^item> The main logical entities (\secref{ch:logic}) have established
   7.292 -  naming convention as follows:
   7.293 +  \<^item> The main logical entities (\secref{ch:logic}) have established naming
   7.294 +  convention as follows:
   7.295  
   7.296      \<^item> sorts are called @{ML_text S}
   7.297  
   7.298 -    \<^item> types are called @{ML_text T}, @{ML_text U}, or @{ML_text
   7.299 -    ty} (never @{ML_text t})
   7.300 +    \<^item> types are called @{ML_text T}, @{ML_text U}, or @{ML_text ty} (never
   7.301 +    @{ML_text t})
   7.302  
   7.303 -    \<^item> terms are called @{ML_text t}, @{ML_text u}, or @{ML_text
   7.304 -    tm} (never @{ML_text trm})
   7.305 +    \<^item> terms are called @{ML_text t}, @{ML_text u}, or @{ML_text tm} (never
   7.306 +    @{ML_text trm})
   7.307  
   7.308 -    \<^item> certified types are called @{ML_text cT}, rarely @{ML_text
   7.309 -    T}, with variants as for types
   7.310 +    \<^item> certified types are called @{ML_text cT}, rarely @{ML_text T}, with
   7.311 +    variants as for types
   7.312  
   7.313 -    \<^item> certified terms are called @{ML_text ct}, rarely @{ML_text
   7.314 -    t}, with variants as for terms (never @{ML_text ctrm})
   7.315 +    \<^item> certified terms are called @{ML_text ct}, rarely @{ML_text t}, with
   7.316 +    variants as for terms (never @{ML_text ctrm})
   7.317  
   7.318      \<^item> theorems are called @{ML_text th}, or @{ML_text thm}
   7.319  
   7.320 -  Proper semantic names override these conventions completely.  For
   7.321 -  example, the left-hand side of an equation (as a term) can be called
   7.322 -  @{ML_text lhs} (not @{ML_text lhs_tm}).  Or a term that is known
   7.323 -  to be a variable can be called @{ML_text v} or @{ML_text x}.
   7.324 +  Proper semantic names override these conventions completely. For example,
   7.325 +  the left-hand side of an equation (as a term) can be called @{ML_text lhs}
   7.326 +  (not @{ML_text lhs_tm}). Or a term that is known to be a variable can be
   7.327 +  called @{ML_text v} or @{ML_text x}.
   7.328  
   7.329 -  \<^item> Tactics (\secref{sec:tactics}) are sufficiently important to
   7.330 -  have specific naming conventions.  The name of a basic tactic
   7.331 -  definition always has a @{ML_text "_tac"} suffix, the subgoal index
   7.332 -  (if applicable) is always called @{ML_text i}, and the goal state
   7.333 -  (if made explicit) is usually called @{ML_text st} instead of the
   7.334 -  somewhat misleading @{ML_text thm}.  Any other arguments are given
   7.335 -  before the latter two, and the general context is given first.
   7.336 -  Example:
   7.337 +  \<^item> Tactics (\secref{sec:tactics}) are sufficiently important to have specific
   7.338 +  naming conventions. The name of a basic tactic definition always has a
   7.339 +  @{ML_text "_tac"} suffix, the subgoal index (if applicable) is always called
   7.340 +  @{ML_text i}, and the goal state (if made explicit) is usually called
   7.341 +  @{ML_text st} instead of the somewhat misleading @{ML_text thm}. Any other
   7.342 +  arguments are given before the latter two, and the general context is given
   7.343 +  first. Example:
   7.344  
   7.345    @{verbatim [display] \<open>  fun my_tac ctxt arg1 arg2 i st = ...\<close>}
   7.346  
   7.347 -  Note that the goal state @{ML_text st} above is rarely made
   7.348 -  explicit, if tactic combinators (tacticals) are used as usual.
   7.349 +  Note that the goal state @{ML_text st} above is rarely made explicit, if
   7.350 +  tactic combinators (tacticals) are used as usual.
   7.351  
   7.352    A tactic that requires a proof context needs to make that explicit as seen
   7.353 -  in the \<^verbatim>\<open>ctxt\<close> argument above. Do not refer to the background
   7.354 -  theory of \<^verbatim>\<open>st\<close> -- it is not a proper context, but merely a formal
   7.355 -  certificate.
   7.356 +  in the \<^verbatim>\<open>ctxt\<close> argument above. Do not refer to the background theory of
   7.357 +  \<^verbatim>\<open>st\<close> -- it is not a proper context, but merely a formal certificate.
   7.358  \<close>
   7.359  
   7.360  
   7.361 @@ -275,30 +270,34 @@
   7.362  text \<open>
   7.363    The general Isabelle/ML source layout imitates regular type-setting
   7.364    conventions, augmented by the requirements for deeply nested expressions
   7.365 -  that are commonplace in functional programming.\<close>
   7.366 +  that are commonplace in functional programming.
   7.367 +\<close>
   7.368  
   7.369  paragraph \<open>Line length\<close>
   7.370 -text \<open>is limited to 80 characters according to ancient standards, but we allow
   7.371 -  as much as 100 characters (not more).\<^footnote>\<open>Readability requires to keep
   7.372 -  the beginning of a line in view while watching its end. Modern wide-screen
   7.373 +text \<open>
   7.374 +  is limited to 80 characters according to ancient standards, but we allow as
   7.375 +  much as 100 characters (not more).\<^footnote>\<open>Readability requires to keep the
   7.376 +  beginning of a line in view while watching its end. Modern wide-screen
   7.377    displays do not change the way how the human brain works. Sources also need
   7.378    to be printable on plain paper with reasonable font-size.\<close> The extra 20
   7.379    characters acknowledge the space requirements due to qualified library
   7.380 -  references in Isabelle/ML.\<close>
   7.381 +  references in Isabelle/ML.
   7.382 +\<close>
   7.383  
   7.384  paragraph \<open>White-space\<close>
   7.385 -text \<open>is used to emphasize the structure of expressions, following mostly
   7.386 -  standard conventions for mathematical typesetting, as can be seen in plain
   7.387 -  {\TeX} or {\LaTeX}. This defines positioning of spaces for parentheses,
   7.388 -  punctuation, and infixes as illustrated here:
   7.389 +text \<open>
   7.390 +  is used to emphasize the structure of expressions, following mostly standard
   7.391 +  conventions for mathematical typesetting, as can be seen in plain {\TeX} or
   7.392 +  {\LaTeX}. This defines positioning of spaces for parentheses, punctuation,
   7.393 +  and infixes as illustrated here:
   7.394  
   7.395    @{verbatim [display]
   7.396  \<open>  val x = y + z * (a + b);
   7.397    val pair = (a, b);
   7.398    val record = {foo = 1, bar = 2};\<close>}
   7.399  
   7.400 -  Lines are normally broken \<^emph>\<open>after\<close> an infix operator or
   7.401 -  punctuation character.  For example:
   7.402 +  Lines are normally broken \<^emph>\<open>after\<close> an infix operator or punctuation
   7.403 +  character. For example:
   7.404  
   7.405    @{verbatim [display]
   7.406  \<open>
   7.407 @@ -313,32 +312,32 @@
   7.408      c);
   7.409  \<close>}
   7.410  
   7.411 -  Some special infixes (e.g.\ @{ML_text "|>"}) work better at the
   7.412 -  start of the line, but punctuation is always at the end.
   7.413 +  Some special infixes (e.g.\ @{ML_text "|>"}) work better at the start of the
   7.414 +  line, but punctuation is always at the end.
   7.415  
   7.416 -  Function application follows the tradition of \<open>\<lambda>\<close>-calculus,
   7.417 -  not informal mathematics.  For example: @{ML_text "f a b"} for a
   7.418 -  curried function, or @{ML_text "g (a, b)"} for a tupled function.
   7.419 -  Note that the space between @{ML_text g} and the pair @{ML_text
   7.420 -  "(a, b)"} follows the important principle of
   7.421 -  \<^emph>\<open>compositionality\<close>: the layout of @{ML_text "g p"} does not
   7.422 -  change when @{ML_text "p"} is refined to the concrete pair
   7.423 -  @{ML_text "(a, b)"}.
   7.424 +  Function application follows the tradition of \<open>\<lambda>\<close>-calculus, not informal
   7.425 +  mathematics. For example: @{ML_text "f a b"} for a curried function, or
   7.426 +  @{ML_text "g (a, b)"} for a tupled function. Note that the space between
   7.427 +  @{ML_text g} and the pair @{ML_text "(a, b)"} follows the important
   7.428 +  principle of \<^emph>\<open>compositionality\<close>: the layout of @{ML_text "g p"} does not
   7.429 +  change when @{ML_text "p"} is refined to the concrete pair @{ML_text "(a,
   7.430 +  b)"}.
   7.431  \<close>
   7.432  
   7.433  paragraph \<open>Indentation\<close>
   7.434 -text \<open>uses plain spaces, never hard tabulators.\<^footnote>\<open>Tabulators were
   7.435 -  invented to move the carriage of a type-writer to certain predefined
   7.436 -  positions. In software they could be used as a primitive run-length
   7.437 -  compression of consecutive spaces, but the precise result would depend on
   7.438 -  non-standardized text editor configuration.\<close>
   7.439 +text \<open>
   7.440 +  uses plain spaces, never hard tabulators.\<^footnote>\<open>Tabulators were invented to move
   7.441 +  the carriage of a type-writer to certain predefined positions. In software
   7.442 +  they could be used as a primitive run-length compression of consecutive
   7.443 +  spaces, but the precise result would depend on non-standardized text editor
   7.444 +  configuration.\<close>
   7.445  
   7.446 -  Each level of nesting is indented by 2 spaces, sometimes 1, very
   7.447 -  rarely 4, never 8 or any other odd number.
   7.448 +  Each level of nesting is indented by 2 spaces, sometimes 1, very rarely 4,
   7.449 +  never 8 or any other odd number.
   7.450  
   7.451 -  Indentation follows a simple logical format that only depends on the
   7.452 -  nesting depth, not the accidental length of the text that initiates
   7.453 -  a level of nesting.  Example:
   7.454 +  Indentation follows a simple logical format that only depends on the nesting
   7.455 +  depth, not the accidental length of the text that initiates a level of
   7.456 +  nesting. Example:
   7.457  
   7.458    @{verbatim [display]
   7.459  \<open>  (* RIGHT *)
   7.460 @@ -358,29 +357,27 @@
   7.461    else expr2_part1
   7.462         expr2_part2\<close>}
   7.463  
   7.464 -  The second form has many problems: it assumes a fixed-width font
   7.465 -  when viewing the sources, it uses more space on the line and thus
   7.466 -  makes it hard to observe its strict length limit (working against
   7.467 -  \<^emph>\<open>readability\<close>), it requires extra editing to adapt the layout
   7.468 -  to changes of the initial text (working against
   7.469 -  \<^emph>\<open>maintainability\<close>) etc.
   7.470 +  The second form has many problems: it assumes a fixed-width font when
   7.471 +  viewing the sources, it uses more space on the line and thus makes it hard
   7.472 +  to observe its strict length limit (working against \<^emph>\<open>readability\<close>), it
   7.473 +  requires extra editing to adapt the layout to changes of the initial text
   7.474 +  (working against \<^emph>\<open>maintainability\<close>) etc.
   7.475  
   7.476    \<^medskip>
   7.477 -  For similar reasons, any kind of two-dimensional or tabular
   7.478 -  layouts, ASCII-art with lines or boxes of asterisks etc.\ should be
   7.479 -  avoided.
   7.480 +  For similar reasons, any kind of two-dimensional or tabular layouts,
   7.481 +  ASCII-art with lines or boxes of asterisks etc.\ should be avoided.
   7.482  \<close>
   7.483  
   7.484  paragraph \<open>Complex expressions\<close>
   7.485 -
   7.486 -text \<open>that consist of multi-clausal function definitions, @{ML_text handle},
   7.487 +text \<open>
   7.488 +  that consist of multi-clausal function definitions, @{ML_text handle},
   7.489    @{ML_text case}, @{ML_text let} (and combinations) require special
   7.490    attention. The syntax of Standard ML is quite ambitious and admits a lot of
   7.491    variance that can distort the meaning of the text.
   7.492  
   7.493    Multiple clauses of @{ML_text fun}, @{ML_text fn}, @{ML_text handle},
   7.494 -  @{ML_text case} get extra indentation to indicate the nesting
   7.495 -  clearly.  Example:
   7.496 +  @{ML_text case} get extra indentation to indicate the nesting clearly.
   7.497 +  Example:
   7.498  
   7.499    @{verbatim [display]
   7.500  \<open>  (* RIGHT *)
   7.501 @@ -398,10 +395,9 @@
   7.502      | foo p2 =
   7.503      expr2\<close>}
   7.504  
   7.505 -  Body expressions consisting of @{ML_text case} or @{ML_text let}
   7.506 -  require care to maintain compositionality, to prevent loss of
   7.507 -  logical indentation where it is especially important to see the
   7.508 -  structure of the text.  Example:
   7.509 +  Body expressions consisting of @{ML_text case} or @{ML_text let} require
   7.510 +  care to maintain compositionality, to prevent loss of logical indentation
   7.511 +  where it is especially important to see the structure of the text. Example:
   7.512  
   7.513    @{verbatim [display]
   7.514  \<open>  (* RIGHT *)
   7.515 @@ -430,13 +426,12 @@
   7.516        ...
   7.517      end\<close>}
   7.518  
   7.519 -  Extra parentheses around @{ML_text case} expressions are optional,
   7.520 -  but help to analyse the nesting based on character matching in the
   7.521 -  text editor.
   7.522 +  Extra parentheses around @{ML_text case} expressions are optional, but help
   7.523 +  to analyse the nesting based on character matching in the text editor.
   7.524  
   7.525    \<^medskip>
   7.526 -  There are two main exceptions to the overall principle of
   7.527 -  compositionality in the layout of complex expressions.
   7.528 +  There are two main exceptions to the overall principle of compositionality
   7.529 +  in the layout of complex expressions.
   7.530  
   7.531    \<^enum> @{ML_text "if"} expressions are iterated as if ML had multi-branch
   7.532    conditionals, e.g.
   7.533 @@ -448,10 +443,10 @@
   7.534    else if b2 then e2
   7.535    else e3\<close>}
   7.536  
   7.537 -  \<^enum> @{ML_text fn} abstractions are often layed-out as if they
   7.538 -  would lack any structure by themselves.  This traditional form is
   7.539 -  motivated by the possibility to shift function arguments back and
   7.540 -  forth wrt.\ additional combinators.  Example:
   7.541 +  \<^enum> @{ML_text fn} abstractions are often layed-out as if they would lack any
   7.542 +  structure by themselves. This traditional form is motivated by the
   7.543 +  possibility to shift function arguments back and forth wrt.\ additional
   7.544 +  combinators. Example:
   7.545  
   7.546    @{verbatim [display]
   7.547  \<open>  (* RIGHT *)
   7.548 @@ -463,8 +458,8 @@
   7.549    @{ML_text y}, @{ML_text z} in a row.
   7.550  
   7.551  
   7.552 -  Such weakly structured layout should be use with great care.  Here
   7.553 -  are some counter-examples involving @{ML_text let} expressions:
   7.554 +  Such weakly structured layout should be use with great care. Here are some
   7.555 +  counter-examples involving @{ML_text let} expressions:
   7.556  
   7.557    @{verbatim [display]
   7.558  \<open>  (* WRONG *)
   7.559 @@ -498,19 +493,19 @@
   7.560        ... end\<close>}
   7.561  
   7.562    \<^medskip>
   7.563 -  In general the source layout is meant to emphasize the
   7.564 -  structure of complex language expressions, not to pretend that SML
   7.565 -  had a completely different syntax (say that of Haskell, Scala, Java).
   7.566 +  In general the source layout is meant to emphasize the structure of complex
   7.567 +  language expressions, not to pretend that SML had a completely different
   7.568 +  syntax (say that of Haskell, Scala, Java).
   7.569  \<close>
   7.570  
   7.571  
   7.572  section \<open>ML embedded into Isabelle/Isar\<close>
   7.573  
   7.574 -text \<open>ML and Isar are intertwined via an open-ended bootstrap
   7.575 -  process that provides more and more programming facilities and
   7.576 -  logical content in an alternating manner.  Bootstrapping starts from
   7.577 -  the raw environment of existing implementations of Standard ML
   7.578 -  (mainly Poly/ML, but also SML/NJ).
   7.579 +text \<open>
   7.580 +  ML and Isar are intertwined via an open-ended bootstrap process that
   7.581 +  provides more and more programming facilities and logical content in an
   7.582 +  alternating manner. Bootstrapping starts from the raw environment of
   7.583 +  existing implementations of Standard ML (mainly Poly/ML, but also SML/NJ).
   7.584  
   7.585    Isabelle/Pure marks the point where the raw ML toplevel is superseded by
   7.586    Isabelle/ML within the Isar theory and proof language, with a uniform
   7.587 @@ -521,11 +516,11 @@
   7.588    Object-logics like Isabelle/HOL are built within the Isabelle/ML/Isar
   7.589    environment by introducing suitable theories with associated ML modules,
   7.590    either inlined within \<^verbatim>\<open>.thy\<close> files, or as separate \<^verbatim>\<open>.ML\<close> files that are
   7.591 -  loading from some theory. Thus Isabelle/HOL is defined
   7.592 -  as a regular user-space application within the Isabelle framework. Further
   7.593 -  add-on tools can be implemented in ML within the Isar context in the same
   7.594 -  manner: ML is part of the standard repertoire of Isabelle, and there is no
   7.595 -  distinction between ``users'' and ``developers'' in this respect.
   7.596 +  loading from some theory. Thus Isabelle/HOL is defined as a regular
   7.597 +  user-space application within the Isabelle framework. Further add-on tools
   7.598 +  can be implemented in ML within the Isar context in the same manner: ML is
   7.599 +  part of the standard repertoire of Isabelle, and there is no distinction
   7.600 +  between ``users'' and ``developers'' in this respect.
   7.601  \<close>
   7.602  
   7.603  
   7.604 @@ -543,10 +538,10 @@
   7.605    pending goal state via a given expression of type @{ML_type tactic}.
   7.606  \<close>
   7.607  
   7.608 -text %mlex \<open>The following artificial example demonstrates some ML
   7.609 -  toplevel declarations within the implicit Isar theory context.  This
   7.610 -  is regular functional programming without referring to logical
   7.611 -  entities yet.
   7.612 +text %mlex \<open>
   7.613 +  The following artificial example demonstrates some ML toplevel declarations
   7.614 +  within the implicit Isar theory context. This is regular functional
   7.615 +  programming without referring to logical entities yet.
   7.616  \<close>
   7.617  
   7.618  ML \<open>
   7.619 @@ -554,24 +549,25 @@
   7.620      | factorial n = n * factorial (n - 1)
   7.621  \<close>
   7.622  
   7.623 -text \<open>Here the ML environment is already managed by Isabelle, i.e.\
   7.624 -  the @{ML factorial} function is not yet accessible in the preceding
   7.625 -  paragraph, nor in a different theory that is independent from the
   7.626 -  current one in the import hierarchy.
   7.627 +text \<open>
   7.628 +  Here the ML environment is already managed by Isabelle, i.e.\ the @{ML
   7.629 +  factorial} function is not yet accessible in the preceding paragraph, nor in
   7.630 +  a different theory that is independent from the current one in the import
   7.631 +  hierarchy.
   7.632  
   7.633    Removing the above ML declaration from the source text will remove any trace
   7.634    of this definition, as expected. The Isabelle/ML toplevel environment is
   7.635 -  managed in a \<^emph>\<open>stateless\<close> way: in contrast to the raw ML toplevel, there
   7.636 -  are no global side-effects involved here.\<^footnote>\<open>Such a stateless
   7.637 -  compilation environment is also a prerequisite for robust parallel
   7.638 -  compilation within independent nodes of the implicit theory development
   7.639 -  graph.\<close>
   7.640 +  managed in a \<^emph>\<open>stateless\<close> way: in contrast to the raw ML toplevel, there are
   7.641 +  no global side-effects involved here.\<^footnote>\<open>Such a stateless compilation
   7.642 +  environment is also a prerequisite for robust parallel compilation within
   7.643 +  independent nodes of the implicit theory development graph.\<close>
   7.644  
   7.645    \<^medskip>
   7.646 -  The next example shows how to embed ML into Isar proofs, using
   7.647 -  @{command_ref "ML_prf"} instead of @{command_ref "ML"}. As illustrated
   7.648 -  below, the effect on the ML environment is local to the whole proof body,
   7.649 -  but ignoring the block structure.\<close>
   7.650 +  The next example shows how to embed ML into Isar proofs, using @{command_ref
   7.651 +  "ML_prf"} instead of @{command_ref "ML"}. As illustrated below, the effect
   7.652 +  on the ML environment is local to the whole proof body, but ignoring the
   7.653 +  block structure.
   7.654 +\<close>
   7.655  
   7.656  notepad
   7.657  begin
   7.658 @@ -582,19 +578,19 @@
   7.659    ML_prf %"ML" \<open>val c = b + 1\<close>
   7.660  end
   7.661  
   7.662 -text \<open>By side-stepping the normal scoping rules for Isar proof
   7.663 -  blocks, embedded ML code can refer to the different contexts and
   7.664 -  manipulate corresponding entities, e.g.\ export a fact from a block
   7.665 -  context.
   7.666 +text \<open>
   7.667 +  By side-stepping the normal scoping rules for Isar proof blocks, embedded ML
   7.668 +  code can refer to the different contexts and manipulate corresponding
   7.669 +  entities, e.g.\ export a fact from a block context.
   7.670  
   7.671    \<^medskip>
   7.672 -  Two further ML commands are useful in certain situations:
   7.673 -  @{command_ref ML_val} and @{command_ref ML_command} are \<^emph>\<open>diagnostic\<close> in
   7.674 -  the sense that there is no effect on the underlying environment, and can
   7.675 -  thus be used anywhere. The examples below produce long strings of digits by
   7.676 -  invoking @{ML factorial}: @{command ML_val} takes care of printing the ML
   7.677 -  toplevel result, but @{command ML_command} is silent so we produce an
   7.678 -  explicit output message.
   7.679 +  Two further ML commands are useful in certain situations: @{command_ref
   7.680 +  ML_val} and @{command_ref ML_command} are \<^emph>\<open>diagnostic\<close> in the sense that
   7.681 +  there is no effect on the underlying environment, and can thus be used
   7.682 +  anywhere. The examples below produce long strings of digits by invoking @{ML
   7.683 +  factorial}: @{command ML_val} takes care of printing the ML toplevel result,
   7.684 +  but @{command ML_command} is silent so we produce an explicit output
   7.685 +  message.
   7.686  \<close>
   7.687  
   7.688  ML_val \<open>factorial 100\<close>
   7.689 @@ -609,12 +605,13 @@
   7.690  
   7.691  subsection \<open>Compile-time context\<close>
   7.692  
   7.693 -text \<open>Whenever the ML compiler is invoked within Isabelle/Isar, the
   7.694 -  formal context is passed as a thread-local reference variable.  Thus
   7.695 -  ML code may access the theory context during compilation, by reading
   7.696 -  or writing the (local) theory under construction.  Note that such
   7.697 -  direct access to the compile-time context is rare.  In practice it
   7.698 -  is typically done via some derived ML functions instead.
   7.699 +text \<open>
   7.700 +  Whenever the ML compiler is invoked within Isabelle/Isar, the formal context
   7.701 +  is passed as a thread-local reference variable. Thus ML code may access the
   7.702 +  theory context during compilation, by reading or writing the (local) theory
   7.703 +  under construction. Note that such direct access to the compile-time context
   7.704 +  is rare. In practice it is typically done via some derived ML functions
   7.705 +  instead.
   7.706  \<close>
   7.707  
   7.708  text %mlref \<open>
   7.709 @@ -625,36 +622,35 @@
   7.710    @{index_ML ML_Thms.bind_thm: "string * thm -> unit"} \\
   7.711    \end{mldecls}
   7.712  
   7.713 -  \<^descr> @{ML "ML_Context.the_generic_context ()"} refers to the theory
   7.714 -  context of the ML toplevel --- at compile time.  ML code needs to
   7.715 -  take care to refer to @{ML "ML_Context.the_generic_context ()"}
   7.716 -  correctly.  Recall that evaluation of a function body is delayed
   7.717 -  until actual run-time.
   7.718 +    \<^descr> @{ML "ML_Context.the_generic_context ()"} refers to the theory context of
   7.719 +    the ML toplevel --- at compile time. ML code needs to take care to refer to
   7.720 +    @{ML "ML_Context.the_generic_context ()"} correctly. Recall that evaluation
   7.721 +    of a function body is delayed until actual run-time.
   7.722  
   7.723 -  \<^descr> @{ML "Context.>>"}~\<open>f\<close> applies context transformation
   7.724 -  \<open>f\<close> to the implicit context of the ML toplevel.
   7.725 +    \<^descr> @{ML "Context.>>"}~\<open>f\<close> applies context transformation \<open>f\<close> to the implicit
   7.726 +    context of the ML toplevel.
   7.727  
   7.728 -  \<^descr> @{ML ML_Thms.bind_thms}~\<open>(name, thms)\<close> stores a list of
   7.729 -  theorems produced in ML both in the (global) theory context and the
   7.730 -  ML toplevel, associating it with the provided name.
   7.731 -
   7.732 -  \<^descr> @{ML ML_Thms.bind_thm} is similar to @{ML ML_Thms.bind_thms} but
   7.733 -  refers to a singleton fact.
   7.734 +    \<^descr> @{ML ML_Thms.bind_thms}~\<open>(name, thms)\<close> stores a list of theorems produced
   7.735 +    in ML both in the (global) theory context and the ML toplevel, associating
   7.736 +    it with the provided name.
   7.737  
   7.738 +    \<^descr> @{ML ML_Thms.bind_thm} is similar to @{ML ML_Thms.bind_thms} but refers to
   7.739 +    a singleton fact.
   7.740  
   7.741 -  It is important to note that the above functions are really
   7.742 -  restricted to the compile time, even though the ML compiler is
   7.743 -  invoked at run-time.  The majority of ML code either uses static
   7.744 -  antiquotations (\secref{sec:ML-antiq}) or refers to the theory or
   7.745 -  proof context at run-time, by explicit functional abstraction.
   7.746 +  It is important to note that the above functions are really restricted to
   7.747 +  the compile time, even though the ML compiler is invoked at run-time. The
   7.748 +  majority of ML code either uses static antiquotations
   7.749 +  (\secref{sec:ML-antiq}) or refers to the theory or proof context at
   7.750 +  run-time, by explicit functional abstraction.
   7.751  \<close>
   7.752  
   7.753  
   7.754  subsection \<open>Antiquotations \label{sec:ML-antiq}\<close>
   7.755  
   7.756 -text \<open>A very important consequence of embedding ML into Isar is the
   7.757 -  concept of \<^emph>\<open>ML antiquotation\<close>.  The standard token language of
   7.758 -  ML is augmented by special syntactic entities of the following form:
   7.759 +text \<open>
   7.760 +  A very important consequence of embedding ML into Isar is the concept of
   7.761 +  \<^emph>\<open>ML antiquotation\<close>. The standard token language of ML is augmented by
   7.762 +  special syntactic entities of the following form:
   7.763  
   7.764    @{rail \<open>
   7.765    @{syntax_def antiquote}: '@{' nameref args '}'
   7.766 @@ -664,30 +660,29 @@
   7.767    defined in @{cite "isabelle-isar-ref"}.
   7.768  
   7.769    \<^medskip>
   7.770 -  A regular antiquotation \<open>@{name args}\<close> processes
   7.771 -  its arguments by the usual means of the Isar source language, and
   7.772 -  produces corresponding ML source text, either as literal
   7.773 -  \<^emph>\<open>inline\<close> text (e.g.\ \<open>@{term t}\<close>) or abstract
   7.774 -  \<^emph>\<open>value\<close> (e.g. \<open>@{thm th}\<close>).  This pre-compilation
   7.775 -  scheme allows to refer to formal entities in a robust manner, with
   7.776 -  proper static scoping and with some degree of logical checking of
   7.777 -  small portions of the code.
   7.778 +  A regular antiquotation \<open>@{name args}\<close> processes its arguments by the usual
   7.779 +  means of the Isar source language, and produces corresponding ML source
   7.780 +  text, either as literal \<^emph>\<open>inline\<close> text (e.g.\ \<open>@{term t}\<close>) or abstract
   7.781 +  \<^emph>\<open>value\<close> (e.g. \<open>@{thm th}\<close>). This pre-compilation scheme allows to refer to
   7.782 +  formal entities in a robust manner, with proper static scoping and with some
   7.783 +  degree of logical checking of small portions of the code.
   7.784  \<close>
   7.785  
   7.786  
   7.787  subsection \<open>Printing ML values\<close>
   7.788  
   7.789 -text \<open>The ML compiler knows about the structure of values according
   7.790 -  to their static type, and can print them in the manner of its
   7.791 -  toplevel, although the details are non-portable.  The
   7.792 -  antiquotations @{ML_antiquotation_def "make_string"} and
   7.793 -  @{ML_antiquotation_def "print"} provide a quasi-portable way to
   7.794 -  refer to this potential capability of the underlying ML system in
   7.795 +text \<open>
   7.796 +  The ML compiler knows about the structure of values according to their
   7.797 +  static type, and can print them in the manner of its toplevel, although the
   7.798 +  details are non-portable. The antiquotations @{ML_antiquotation_def
   7.799 +  "make_string"} and @{ML_antiquotation_def "print"} provide a quasi-portable
   7.800 +  way to refer to this potential capability of the underlying ML system in
   7.801    generic Isabelle/ML sources.
   7.802  
   7.803 -  This is occasionally useful for diagnostic or demonstration
   7.804 -  purposes.  Note that production-quality tools require proper
   7.805 -  user-level error messages, avoiding raw ML values in the output.\<close>
   7.806 +  This is occasionally useful for diagnostic or demonstration purposes. Note
   7.807 +  that production-quality tools require proper user-level error messages,
   7.808 +  avoiding raw ML values in the output.
   7.809 +\<close>
   7.810  
   7.811  text %mlantiq \<open>
   7.812    \begin{matharray}{rcl}
   7.813 @@ -701,19 +696,20 @@
   7.814    @@{ML_antiquotation print} @{syntax name}?
   7.815    \<close>}
   7.816  
   7.817 -  \<^descr> \<open>@{make_string}\<close> inlines a function to print arbitrary values
   7.818 -  similar to the ML toplevel. The result is compiler dependent and may fall
   7.819 -  back on "?" in certain situations. The value of configuration option
   7.820 -  @{attribute_ref ML_print_depth} determines further details of output.
   7.821 +  \<^descr> \<open>@{make_string}\<close> inlines a function to print arbitrary values similar to
   7.822 +  the ML toplevel. The result is compiler dependent and may fall back on "?"
   7.823 +  in certain situations. The value of configuration option @{attribute_ref
   7.824 +  ML_print_depth} determines further details of output.
   7.825  
   7.826 -  \<^descr> \<open>@{print f}\<close> uses the ML function \<open>f: string ->
   7.827 -  unit\<close> to output the result of \<open>@{make_string}\<close> above,
   7.828 -  together with the source position of the antiquotation.  The default
   7.829 -  output function is @{ML writeln}.
   7.830 +  \<^descr> \<open>@{print f}\<close> uses the ML function \<open>f: string -> unit\<close> to output the result
   7.831 +  of \<open>@{make_string}\<close> above, together with the source position of the
   7.832 +  antiquotation. The default output function is @{ML writeln}.
   7.833  \<close>
   7.834  
   7.835 -text %mlex \<open>The following artificial examples show how to produce
   7.836 -  adhoc output of ML values for debugging purposes.\<close>
   7.837 +text %mlex \<open>
   7.838 +  The following artificial examples show how to produce adhoc output of ML
   7.839 +  values for debugging purposes.
   7.840 +\<close>
   7.841  
   7.842  ML_val \<open>
   7.843    val x = 42;
   7.844 @@ -728,47 +724,44 @@
   7.845  
   7.846  section \<open>Canonical argument order \label{sec:canonical-argument-order}\<close>
   7.847  
   7.848 -text \<open>Standard ML is a language in the tradition of \<open>\<lambda>\<close>-calculus and \<^emph>\<open>higher-order functional programming\<close>,
   7.849 -  similar to OCaml, Haskell, or Isabelle/Pure and HOL as logical
   7.850 -  languages.  Getting acquainted with the native style of representing
   7.851 -  functions in that setting can save a lot of extra boiler-plate of
   7.852 -  redundant shuffling of arguments, auxiliary abstractions etc.
   7.853 +text \<open>
   7.854 +  Standard ML is a language in the tradition of \<open>\<lambda>\<close>-calculus and
   7.855 +  \<^emph>\<open>higher-order functional programming\<close>, similar to OCaml, Haskell, or
   7.856 +  Isabelle/Pure and HOL as logical languages. Getting acquainted with the
   7.857 +  native style of representing functions in that setting can save a lot of
   7.858 +  extra boiler-plate of redundant shuffling of arguments, auxiliary
   7.859 +  abstractions etc.
   7.860  
   7.861 -  Functions are usually \<^emph>\<open>curried\<close>: the idea of turning arguments
   7.862 -  of type \<open>\<tau>\<^sub>i\<close> (for \<open>i \<in> {1, \<dots> n}\<close>) into a result of
   7.863 -  type \<open>\<tau>\<close> is represented by the iterated function space
   7.864 -  \<open>\<tau>\<^sub>1 \<rightarrow> \<dots> \<rightarrow> \<tau>\<^sub>n \<rightarrow> \<tau>\<close>.  This is isomorphic to the well-known
   7.865 -  encoding via tuples \<open>\<tau>\<^sub>1 \<times> \<dots> \<times> \<tau>\<^sub>n \<rightarrow> \<tau>\<close>, but the curried
   7.866 -  version fits more smoothly into the basic calculus.\<^footnote>\<open>The
   7.867 -  difference is even more significant in HOL, because the redundant
   7.868 -  tuple structure needs to be accommodated extraneous proof steps.\<close>
   7.869 +  Functions are usually \<^emph>\<open>curried\<close>: the idea of turning arguments of type
   7.870 +  \<open>\<tau>\<^sub>i\<close> (for \<open>i \<in> {1, \<dots> n}\<close>) into a result of type \<open>\<tau>\<close> is represented by the
   7.871 +  iterated function space \<open>\<tau>\<^sub>1 \<rightarrow> \<dots> \<rightarrow> \<tau>\<^sub>n \<rightarrow> \<tau>\<close>. This is isomorphic to the
   7.872 +  well-known encoding via tuples \<open>\<tau>\<^sub>1 \<times> \<dots> \<times> \<tau>\<^sub>n \<rightarrow> \<tau>\<close>, but the curried version
   7.873 +  fits more smoothly into the basic calculus.\<^footnote>\<open>The difference is even more
   7.874 +  significant in HOL, because the redundant tuple structure needs to be
   7.875 +  accommodated extraneous proof steps.\<close>
   7.876  
   7.877 -  Currying gives some flexibility due to \<^emph>\<open>partial application\<close>.  A
   7.878 -  function \<open>f: \<tau>\<^sub>1 \<rightarrow> \<tau>\<^sub>2 \<rightarrow> \<tau>\<close> can be applied to \<open>x: \<tau>\<^sub>1\<close>
   7.879 -  and the remaining \<open>(f x): \<tau>\<^sub>2 \<rightarrow> \<tau>\<close> passed to another function
   7.880 -  etc.  How well this works in practice depends on the order of
   7.881 -  arguments.  In the worst case, arguments are arranged erratically,
   7.882 -  and using a function in a certain situation always requires some
   7.883 -  glue code.  Thus we would get exponentially many opportunities to
   7.884 +  Currying gives some flexibility due to \<^emph>\<open>partial application\<close>. A function
   7.885 +  \<open>f: \<tau>\<^sub>1 \<rightarrow> \<tau>\<^sub>2 \<rightarrow> \<tau>\<close> can be applied to \<open>x: \<tau>\<^sub>1\<close> and the remaining \<open>(f x): \<tau>\<^sub>2
   7.886 +  \<rightarrow> \<tau>\<close> passed to another function etc. How well this works in practice depends
   7.887 +  on the order of arguments. In the worst case, arguments are arranged
   7.888 +  erratically, and using a function in a certain situation always requires
   7.889 +  some glue code. Thus we would get exponentially many opportunities to
   7.890    decorate the code with meaningless permutations of arguments.
   7.891  
   7.892 -  This can be avoided by \<^emph>\<open>canonical argument order\<close>, which
   7.893 -  observes certain standard patterns and minimizes adhoc permutations
   7.894 -  in their application.  In Isabelle/ML, large portions of text can be
   7.895 -  written without auxiliary operations like \<open>swap: \<alpha> \<times> \<beta> \<rightarrow> \<beta> \<times>
   7.896 -  \<alpha>\<close> or \<open>C: (\<alpha> \<rightarrow> \<beta> \<rightarrow> \<gamma>) \<rightarrow> (\<beta> \<rightarrow> \<alpha> \<rightarrow> \<gamma>)\<close> (the latter is not
   7.897 -  present in the Isabelle/ML library).
   7.898 +  This can be avoided by \<^emph>\<open>canonical argument order\<close>, which observes certain
   7.899 +  standard patterns and minimizes adhoc permutations in their application. In
   7.900 +  Isabelle/ML, large portions of text can be written without auxiliary
   7.901 +  operations like \<open>swap: \<alpha> \<times> \<beta> \<rightarrow> \<beta> \<times> \<alpha>\<close> or \<open>C: (\<alpha> \<rightarrow> \<beta> \<rightarrow> \<gamma>) \<rightarrow> (\<beta> \<rightarrow> \<alpha> \<rightarrow> \<gamma>)\<close> (the
   7.902 +  latter is not present in the Isabelle/ML library).
   7.903  
   7.904    \<^medskip>
   7.905 -  The main idea is that arguments that vary less are moved
   7.906 -  further to the left than those that vary more.  Two particularly
   7.907 -  important categories of functions are \<^emph>\<open>selectors\<close> and
   7.908 -  \<^emph>\<open>updates\<close>.
   7.909 +  The main idea is that arguments that vary less are moved further to the left
   7.910 +  than those that vary more. Two particularly important categories of
   7.911 +  functions are \<^emph>\<open>selectors\<close> and \<^emph>\<open>updates\<close>.
   7.912  
   7.913 -  The subsequent scheme is based on a hypothetical set-like container
   7.914 -  of type \<open>\<beta>\<close> that manages elements of type \<open>\<alpha>\<close>.  Both
   7.915 -  the names and types of the associated operations are canonical for
   7.916 -  Isabelle/ML.
   7.917 +  The subsequent scheme is based on a hypothetical set-like container of type
   7.918 +  \<open>\<beta>\<close> that manages elements of type \<open>\<alpha>\<close>. Both the names and types of the
   7.919 +  associated operations are canonical for Isabelle/ML.
   7.920  
   7.921    \begin{center}
   7.922    \begin{tabular}{ll}
   7.923 @@ -778,35 +771,33 @@
   7.924    \end{tabular}
   7.925    \end{center}
   7.926  
   7.927 -  Given a container \<open>B: \<beta>\<close>, the partially applied \<open>member B\<close> is a predicate over elements \<open>\<alpha> \<rightarrow> bool\<close>, and
   7.928 -  thus represents the intended denotation directly.  It is customary
   7.929 -  to pass the abstract predicate to further operations, not the
   7.930 -  concrete container.  The argument order makes it easy to use other
   7.931 -  combinators: \<open>forall (member B) list\<close> will check a list of
   7.932 -  elements for membership in \<open>B\<close> etc. Often the explicit
   7.933 -  \<open>list\<close> is pointless and can be contracted to \<open>forall
   7.934 -  (member B)\<close> to get directly a predicate again.
   7.935 +  Given a container \<open>B: \<beta>\<close>, the partially applied \<open>member B\<close> is a predicate
   7.936 +  over elements \<open>\<alpha> \<rightarrow> bool\<close>, and thus represents the intended denotation
   7.937 +  directly. It is customary to pass the abstract predicate to further
   7.938 +  operations, not the concrete container. The argument order makes it easy to
   7.939 +  use other combinators: \<open>forall (member B) list\<close> will check a list of
   7.940 +  elements for membership in \<open>B\<close> etc. Often the explicit \<open>list\<close> is pointless
   7.941 +  and can be contracted to \<open>forall (member B)\<close> to get directly a predicate
   7.942 +  again.
   7.943  
   7.944 -  In contrast, an update operation varies the container, so it moves
   7.945 -  to the right: \<open>insert a\<close> is a function \<open>\<beta> \<rightarrow> \<beta>\<close> to
   7.946 -  insert a value \<open>a\<close>.  These can be composed naturally as
   7.947 -  \<open>insert c \<circ> insert b \<circ> insert a\<close>.  The slightly awkward
   7.948 -  inversion of the composition order is due to conventional
   7.949 -  mathematical notation, which can be easily amended as explained
   7.950 -  below.
   7.951 +  In contrast, an update operation varies the container, so it moves to the
   7.952 +  right: \<open>insert a\<close> is a function \<open>\<beta> \<rightarrow> \<beta>\<close> to insert a value \<open>a\<close>. These can be
   7.953 +  composed naturally as \<open>insert c \<circ> insert b \<circ> insert a\<close>. The slightly awkward
   7.954 +  inversion of the composition order is due to conventional mathematical
   7.955 +  notation, which can be easily amended as explained below.
   7.956  \<close>
   7.957  
   7.958  
   7.959  subsection \<open>Forward application and composition\<close>
   7.960  
   7.961 -text \<open>Regular function application and infix notation works best for
   7.962 -  relatively deeply structured expressions, e.g.\ \<open>h (f x y + g
   7.963 -  z)\<close>.  The important special case of \<^emph>\<open>linear transformation\<close>
   7.964 -  applies a cascade of functions \<open>f\<^sub>n (\<dots> (f\<^sub>1 x))\<close>.  This
   7.965 -  becomes hard to read and maintain if the functions are themselves
   7.966 -  given as complex expressions.  The notation can be significantly
   7.967 -  improved by introducing \<^emph>\<open>forward\<close> versions of application and
   7.968 -  composition as follows:
   7.969 +text \<open>
   7.970 +  Regular function application and infix notation works best for relatively
   7.971 +  deeply structured expressions, e.g.\ \<open>h (f x y + g z)\<close>. The important
   7.972 +  special case of \<^emph>\<open>linear transformation\<close> applies a cascade of functions \<open>f\<^sub>n
   7.973 +  (\<dots> (f\<^sub>1 x))\<close>. This becomes hard to read and maintain if the functions are
   7.974 +  themselves given as complex expressions. The notation can be significantly
   7.975 +  improved by introducing \<^emph>\<open>forward\<close> versions of application and composition
   7.976 +  as follows:
   7.977  
   7.978    \<^medskip>
   7.979    \begin{tabular}{lll}
   7.980 @@ -815,13 +806,12 @@
   7.981    \end{tabular}
   7.982    \<^medskip>
   7.983  
   7.984 -  This enables to write conveniently \<open>x |> f\<^sub>1 |> \<dots> |> f\<^sub>n\<close> or
   7.985 -  \<open>f\<^sub>1 #> \<dots> #> f\<^sub>n\<close> for its functional abstraction over \<open>x\<close>.
   7.986 +  This enables to write conveniently \<open>x |> f\<^sub>1 |> \<dots> |> f\<^sub>n\<close> or \<open>f\<^sub>1 #> \<dots> #>
   7.987 +  f\<^sub>n\<close> for its functional abstraction over \<open>x\<close>.
   7.988  
   7.989    \<^medskip>
   7.990 -  There is an additional set of combinators to accommodate
   7.991 -  multiple results (via pairs) that are passed on as multiple
   7.992 -  arguments (via currying).
   7.993 +  There is an additional set of combinators to accommodate multiple results
   7.994 +  (via pairs) that are passed on as multiple arguments (via currying).
   7.995  
   7.996    \<^medskip>
   7.997    \begin{tabular}{lll}
   7.998 @@ -843,26 +833,27 @@
   7.999  
  7.1000  subsection \<open>Canonical iteration\<close>
  7.1001  
  7.1002 -text \<open>As explained above, a function \<open>f: \<alpha> \<rightarrow> \<beta> \<rightarrow> \<beta>\<close> can be
  7.1003 -  understood as update on a configuration of type \<open>\<beta>\<close>,
  7.1004 -  parameterized by an argument of type \<open>\<alpha>\<close>.  Given \<open>a: \<alpha>\<close>
  7.1005 -  the partial application \<open>(f a): \<beta> \<rightarrow> \<beta>\<close> operates
  7.1006 -  homogeneously on \<open>\<beta>\<close>.  This can be iterated naturally over a
  7.1007 -  list of parameters \<open>[a\<^sub>1, \<dots>, a\<^sub>n]\<close> as \<open>f a\<^sub>1 #> \<dots> #> f a\<^sub>n\<close>.
  7.1008 -  The latter expression is again a function \<open>\<beta> \<rightarrow> \<beta>\<close>.
  7.1009 -  It can be applied to an initial configuration \<open>b: \<beta>\<close> to
  7.1010 -  start the iteration over the given list of arguments: each \<open>a\<close> in \<open>a\<^sub>1, \<dots>, a\<^sub>n\<close> is applied consecutively by updating a
  7.1011 -  cumulative configuration.
  7.1012 +text \<open>
  7.1013 +  As explained above, a function \<open>f: \<alpha> \<rightarrow> \<beta> \<rightarrow> \<beta>\<close> can be understood as update on
  7.1014 +  a configuration of type \<open>\<beta>\<close>, parameterized by an argument of type \<open>\<alpha>\<close>. Given
  7.1015 +  \<open>a: \<alpha>\<close> the partial application \<open>(f a): \<beta> \<rightarrow> \<beta>\<close> operates homogeneously on \<open>\<beta>\<close>.
  7.1016 +  This can be iterated naturally over a list of parameters \<open>[a\<^sub>1, \<dots>, a\<^sub>n]\<close> as
  7.1017 +  \<open>f a\<^sub>1 #> \<dots> #> f a\<^sub>n\<close>. The latter expression is again a function \<open>\<beta> \<rightarrow> \<beta>\<close>. It
  7.1018 +  can be applied to an initial configuration \<open>b: \<beta>\<close> to start the iteration
  7.1019 +  over the given list of arguments: each \<open>a\<close> in \<open>a\<^sub>1, \<dots>, a\<^sub>n\<close> is applied
  7.1020 +  consecutively by updating a cumulative configuration.
  7.1021  
  7.1022 -  The \<open>fold\<close> combinator in Isabelle/ML lifts a function \<open>f\<close> as above to its iterated version over a list of arguments.
  7.1023 -  Lifting can be repeated, e.g.\ \<open>(fold \<circ> fold) f\<close> iterates
  7.1024 -  over a list of lists as expected.
  7.1025 +  The \<open>fold\<close> combinator in Isabelle/ML lifts a function \<open>f\<close> as above to its
  7.1026 +  iterated version over a list of arguments. Lifting can be repeated, e.g.\
  7.1027 +  \<open>(fold \<circ> fold) f\<close> iterates over a list of lists as expected.
  7.1028  
  7.1029 -  The variant \<open>fold_rev\<close> works inside-out over the list of
  7.1030 -  arguments, such that \<open>fold_rev f \<equiv> fold f \<circ> rev\<close> holds.
  7.1031 +  The variant \<open>fold_rev\<close> works inside-out over the list of arguments, such
  7.1032 +  that \<open>fold_rev f \<equiv> fold f \<circ> rev\<close> holds.
  7.1033  
  7.1034 -  The \<open>fold_map\<close> combinator essentially performs \<open>fold\<close> and \<open>map\<close> simultaneously: each application of \<open>f\<close> produces an updated configuration together with a side-result;
  7.1035 -  the iteration collects all such side-results as a separate list.
  7.1036 +  The \<open>fold_map\<close> combinator essentially performs \<open>fold\<close> and \<open>map\<close>
  7.1037 +  simultaneously: each application of \<open>f\<close> produces an updated configuration
  7.1038 +  together with a side-result; the iteration collects all such side-results as
  7.1039 +  a separate list.
  7.1040  \<close>
  7.1041  
  7.1042  text %mlref \<open>
  7.1043 @@ -872,30 +863,29 @@
  7.1044    @{index_ML fold_map: "('a -> 'b -> 'c * 'b) -> 'a list -> 'b -> 'c list * 'b"} \\
  7.1045    \end{mldecls}
  7.1046  
  7.1047 -  \<^descr> @{ML fold}~\<open>f\<close> lifts the parametrized update function
  7.1048 -  \<open>f\<close> to a list of parameters.
  7.1049 +  \<^descr> @{ML fold}~\<open>f\<close> lifts the parametrized update function \<open>f\<close> to a list of
  7.1050 +  parameters.
  7.1051  
  7.1052 -  \<^descr> @{ML fold_rev}~\<open>f\<close> is similar to @{ML fold}~\<open>f\<close>, but works inside-out, as if the list would be reversed.
  7.1053 +  \<^descr> @{ML fold_rev}~\<open>f\<close> is similar to @{ML fold}~\<open>f\<close>, but works inside-out, as
  7.1054 +  if the list would be reversed.
  7.1055  
  7.1056 -  \<^descr> @{ML fold_map}~\<open>f\<close> lifts the parametrized update
  7.1057 -  function \<open>f\<close> (with side-result) to a list of parameters and
  7.1058 -  cumulative side-results.
  7.1059 +  \<^descr> @{ML fold_map}~\<open>f\<close> lifts the parametrized update function \<open>f\<close> (with
  7.1060 +  side-result) to a list of parameters and cumulative side-results.
  7.1061  
  7.1062  
  7.1063    \begin{warn}
  7.1064    The literature on functional programming provides a confusing multitude of
  7.1065 -  combinators called \<open>foldl\<close>, \<open>foldr\<close> etc. SML97 provides its
  7.1066 -  own variations as @{ML List.foldl} and @{ML List.foldr}, while the classic
  7.1067 -  Isabelle library also has the historic @{ML Library.foldl} and @{ML
  7.1068 -  Library.foldr}. To avoid unnecessary complication, all these historical
  7.1069 -  versions should be ignored, and the canonical @{ML fold} (or @{ML fold_rev})
  7.1070 -  used exclusively.
  7.1071 +  combinators called \<open>foldl\<close>, \<open>foldr\<close> etc. SML97 provides its own variations
  7.1072 +  as @{ML List.foldl} and @{ML List.foldr}, while the classic Isabelle library
  7.1073 +  also has the historic @{ML Library.foldl} and @{ML Library.foldr}. To avoid
  7.1074 +  unnecessary complication, all these historical versions should be ignored,
  7.1075 +  and the canonical @{ML fold} (or @{ML fold_rev}) used exclusively.
  7.1076    \end{warn}
  7.1077  \<close>
  7.1078  
  7.1079 -text %mlex \<open>The following example shows how to fill a text buffer
  7.1080 -  incrementally by adding strings, either individually or from a given
  7.1081 -  list.
  7.1082 +text %mlex \<open>
  7.1083 +  The following example shows how to fill a text buffer incrementally by
  7.1084 +  adding strings, either individually or from a given list.
  7.1085  \<close>
  7.1086  
  7.1087  ML_val \<open>
  7.1088 @@ -908,16 +898,15 @@
  7.1089    @{assert} (s = "digits: 0123456789");
  7.1090  \<close>
  7.1091  
  7.1092 -text \<open>Note how @{ML "fold (Buffer.add o string_of_int)"} above saves
  7.1093 -  an extra @{ML "map"} over the given list.  This kind of peephole
  7.1094 -  optimization reduces both the code size and the tree structures in
  7.1095 -  memory (``deforestation''), but it requires some practice to read
  7.1096 -  and write fluently.
  7.1097 +text \<open>
  7.1098 +  Note how @{ML "fold (Buffer.add o string_of_int)"} above saves an extra @{ML
  7.1099 +  "map"} over the given list. This kind of peephole optimization reduces both
  7.1100 +  the code size and the tree structures in memory (``deforestation''), but it
  7.1101 +  requires some practice to read and write fluently.
  7.1102  
  7.1103    \<^medskip>
  7.1104 -  The next example elaborates the idea of canonical
  7.1105 -  iteration, demonstrating fast accumulation of tree content using a
  7.1106 -  text buffer.
  7.1107 +  The next example elaborates the idea of canonical iteration, demonstrating
  7.1108 +  fast accumulation of tree content using a text buffer.
  7.1109  \<close>
  7.1110  
  7.1111  ML \<open>
  7.1112 @@ -939,51 +928,51 @@
  7.1113      Buffer.empty |> add_content tree |> Buffer.content;
  7.1114  \<close>
  7.1115  
  7.1116 -text \<open>The slowness of @{ML slow_content} is due to the @{ML implode} of
  7.1117 -  the recursive results, because it copies previously produced strings
  7.1118 -  again and again.
  7.1119 +text \<open>
  7.1120 +  The slowness of @{ML slow_content} is due to the @{ML implode} of the
  7.1121 +  recursive results, because it copies previously produced strings again and
  7.1122 +  again.
  7.1123  
  7.1124 -  The incremental @{ML add_content} avoids this by operating on a
  7.1125 -  buffer that is passed through in a linear fashion.  Using @{ML_text
  7.1126 -  "#>"} and contraction over the actual buffer argument saves some
  7.1127 -  additional boiler-plate.  Of course, the two @{ML "Buffer.add"}
  7.1128 -  invocations with concatenated strings could have been split into
  7.1129 -  smaller parts, but this would have obfuscated the source without
  7.1130 -  making a big difference in performance.  Here we have done some
  7.1131 -  peephole-optimization for the sake of readability.
  7.1132 +  The incremental @{ML add_content} avoids this by operating on a buffer that
  7.1133 +  is passed through in a linear fashion. Using @{ML_text "#>"} and contraction
  7.1134 +  over the actual buffer argument saves some additional boiler-plate. Of
  7.1135 +  course, the two @{ML "Buffer.add"} invocations with concatenated strings
  7.1136 +  could have been split into smaller parts, but this would have obfuscated the
  7.1137 +  source without making a big difference in performance. Here we have done
  7.1138 +  some peephole-optimization for the sake of readability.
  7.1139  
  7.1140 -  Another benefit of @{ML add_content} is its ``open'' form as a
  7.1141 -  function on buffers that can be continued in further linear
  7.1142 -  transformations, folding etc.  Thus it is more compositional than
  7.1143 -  the naive @{ML slow_content}.  As realistic example, compare the
  7.1144 -  old-style @{ML "Term.maxidx_of_term: term -> int"} with the newer
  7.1145 -  @{ML "Term.maxidx_term: term -> int -> int"} in Isabelle/Pure.
  7.1146 +  Another benefit of @{ML add_content} is its ``open'' form as a function on
  7.1147 +  buffers that can be continued in further linear transformations, folding
  7.1148 +  etc. Thus it is more compositional than the naive @{ML slow_content}. As
  7.1149 +  realistic example, compare the old-style @{ML "Term.maxidx_of_term: term ->
  7.1150 +  int"} with the newer @{ML "Term.maxidx_term: term -> int -> int"} in
  7.1151 +  Isabelle/Pure.
  7.1152  
  7.1153 -  Note that @{ML fast_content} above is only defined as example.  In
  7.1154 -  many practical situations, it is customary to provide the
  7.1155 -  incremental @{ML add_content} only and leave the initialization and
  7.1156 -  termination to the concrete application to the user.
  7.1157 +  Note that @{ML fast_content} above is only defined as example. In many
  7.1158 +  practical situations, it is customary to provide the incremental @{ML
  7.1159 +  add_content} only and leave the initialization and termination to the
  7.1160 +  concrete application to the user.
  7.1161  \<close>
  7.1162  
  7.1163  
  7.1164  section \<open>Message output channels \label{sec:message-channels}\<close>
  7.1165  
  7.1166 -text \<open>Isabelle provides output channels for different kinds of
  7.1167 -  messages: regular output, high-volume tracing information, warnings,
  7.1168 -  and errors.
  7.1169 +text \<open>
  7.1170 +  Isabelle provides output channels for different kinds of messages: regular
  7.1171 +  output, high-volume tracing information, warnings, and errors.
  7.1172  
  7.1173 -  Depending on the user interface involved, these messages may appear
  7.1174 -  in different text styles or colours.  The standard output for
  7.1175 -  batch sessions prefixes each line of warnings by \<^verbatim>\<open>###\<close> and errors by
  7.1176 -  \<^verbatim>\<open>***\<close>, but leaves anything else
  7.1177 -  unchanged.  The message body may contain further markup and formatting,
  7.1178 -  which is routinely used in the Prover IDE @{cite "isabelle-jedit"}.
  7.1179 +  Depending on the user interface involved, these messages may appear in
  7.1180 +  different text styles or colours. The standard output for batch sessions
  7.1181 +  prefixes each line of warnings by \<^verbatim>\<open>###\<close> and errors by \<^verbatim>\<open>***\<close>, but leaves
  7.1182 +  anything else unchanged. The message body may contain further markup and
  7.1183 +  formatting, which is routinely used in the Prover IDE @{cite
  7.1184 +  "isabelle-jedit"}.
  7.1185  
  7.1186 -  Messages are associated with the transaction context of the running
  7.1187 -  Isar command.  This enables the front-end to manage commands and
  7.1188 -  resulting messages together.  For example, after deleting a command
  7.1189 -  from a given theory document version, the corresponding message
  7.1190 -  output can be retracted from the display.
  7.1191 +  Messages are associated with the transaction context of the running Isar
  7.1192 +  command. This enables the front-end to manage commands and resulting
  7.1193 +  messages together. For example, after deleting a command from a given theory
  7.1194 +  document version, the corresponding message output can be retracted from the
  7.1195 +  display.
  7.1196  \<close>
  7.1197  
  7.1198  text %mlref \<open>
  7.1199 @@ -994,32 +983,29 @@
  7.1200    @{index_ML error: "string -> 'a"} % FIXME Output.error_message (!?) \\
  7.1201    \end{mldecls}
  7.1202  
  7.1203 -  \<^descr> @{ML writeln}~\<open>text\<close> outputs \<open>text\<close> as regular
  7.1204 -  message.  This is the primary message output operation of Isabelle
  7.1205 -  and should be used by default.
  7.1206 +  \<^descr> @{ML writeln}~\<open>text\<close> outputs \<open>text\<close> as regular message. This is the
  7.1207 +  primary message output operation of Isabelle and should be used by default.
  7.1208  
  7.1209 -  \<^descr> @{ML tracing}~\<open>text\<close> outputs \<open>text\<close> as special
  7.1210 -  tracing message, indicating potential high-volume output to the
  7.1211 -  front-end (hundreds or thousands of messages issued by a single
  7.1212 -  command).  The idea is to allow the user-interface to downgrade the
  7.1213 -  quality of message display to achieve higher throughput.
  7.1214 +  \<^descr> @{ML tracing}~\<open>text\<close> outputs \<open>text\<close> as special tracing message, indicating
  7.1215 +  potential high-volume output to the front-end (hundreds or thousands of
  7.1216 +  messages issued by a single command). The idea is to allow the
  7.1217 +  user-interface to downgrade the quality of message display to achieve higher
  7.1218 +  throughput.
  7.1219  
  7.1220 -  Note that the user might have to take special actions to see tracing
  7.1221 -  output, e.g.\ switch to a different output window.  So this channel
  7.1222 -  should not be used for regular output.
  7.1223 +  Note that the user might have to take special actions to see tracing output,
  7.1224 +  e.g.\ switch to a different output window. So this channel should not be
  7.1225 +  used for regular output.
  7.1226  
  7.1227 -  \<^descr> @{ML warning}~\<open>text\<close> outputs \<open>text\<close> as
  7.1228 -  warning, which typically means some extra emphasis on the front-end
  7.1229 -  side (color highlighting, icons, etc.).
  7.1230 +  \<^descr> @{ML warning}~\<open>text\<close> outputs \<open>text\<close> as warning, which typically means some
  7.1231 +  extra emphasis on the front-end side (color highlighting, icons, etc.).
  7.1232  
  7.1233 -  \<^descr> @{ML error}~\<open>text\<close> raises exception @{ML ERROR}~\<open>text\<close> and thus lets the Isar toplevel print \<open>text\<close> on the
  7.1234 -  error channel, which typically means some extra emphasis on the
  7.1235 -  front-end side (color highlighting, icons, etc.).
  7.1236 +  \<^descr> @{ML error}~\<open>text\<close> raises exception @{ML ERROR}~\<open>text\<close> and thus lets the
  7.1237 +  Isar toplevel print \<open>text\<close> on the error channel, which typically means some
  7.1238 +  extra emphasis on the front-end side (color highlighting, icons, etc.).
  7.1239  
  7.1240    This assumes that the exception is not handled before the command
  7.1241 -  terminates.  Handling exception @{ML ERROR}~\<open>text\<close> is a
  7.1242 -  perfectly legal alternative: it means that the error is absorbed
  7.1243 -  without any message output.
  7.1244 +  terminates. Handling exception @{ML ERROR}~\<open>text\<close> is a perfectly legal
  7.1245 +  alternative: it means that the error is absorbed without any message output.
  7.1246  
  7.1247    \begin{warn}
  7.1248    The actual error channel is accessed via @{ML Output.error_message}, but
  7.1249 @@ -1028,28 +1014,28 @@
  7.1250  
  7.1251  
  7.1252    \begin{warn}
  7.1253 -  Regular Isabelle/ML code should output messages exclusively by the
  7.1254 -  official channels.  Using raw I/O on \<^emph>\<open>stdout\<close> or \<^emph>\<open>stderr\<close>
  7.1255 -  instead (e.g.\ via @{ML TextIO.output}) is apt to cause problems in
  7.1256 -  the presence of parallel and asynchronous processing of Isabelle
  7.1257 -  theories.  Such raw output might be displayed by the front-end in
  7.1258 -  some system console log, with a low chance that the user will ever
  7.1259 -  see it.  Moreover, as a genuine side-effect on global process
  7.1260 -  channels, there is no proper way to retract output when Isar command
  7.1261 +  Regular Isabelle/ML code should output messages exclusively by the official
  7.1262 +  channels. Using raw I/O on \<^emph>\<open>stdout\<close> or \<^emph>\<open>stderr\<close> instead (e.g.\ via @{ML
  7.1263 +  TextIO.output}) is apt to cause problems in the presence of parallel and
  7.1264 +  asynchronous processing of Isabelle theories. Such raw output might be
  7.1265 +  displayed by the front-end in some system console log, with a low chance
  7.1266 +  that the user will ever see it. Moreover, as a genuine side-effect on global
  7.1267 +  process channels, there is no proper way to retract output when Isar command
  7.1268    transactions are reset by the system.
  7.1269    \end{warn}
  7.1270  
  7.1271    \begin{warn}
  7.1272 -  The message channels should be used in a message-oriented manner.
  7.1273 -  This means that multi-line output that logically belongs together is
  7.1274 -  issued by a single invocation of @{ML writeln} etc.\ with the
  7.1275 -  functional concatenation of all message constituents.
  7.1276 +  The message channels should be used in a message-oriented manner. This means
  7.1277 +  that multi-line output that logically belongs together is issued by a single
  7.1278 +  invocation of @{ML writeln} etc.\ with the functional concatenation of all
  7.1279 +  message constituents.
  7.1280    \end{warn}
  7.1281  \<close>
  7.1282  
  7.1283 -text %mlex \<open>The following example demonstrates a multi-line
  7.1284 -  warning.  Note that in some situations the user sees only the first
  7.1285 -  line, so the most important point should be made first.
  7.1286 +text %mlex \<open>
  7.1287 +  The following example demonstrates a multi-line warning. Note that in some
  7.1288 +  situations the user sees only the first line, so the most important point
  7.1289 +  should be made first.
  7.1290  \<close>
  7.1291  
  7.1292  ML_command \<open>
  7.1293 @@ -1062,8 +1048,7 @@
  7.1294  
  7.1295  text \<open>
  7.1296    \<^medskip>
  7.1297 -  An alternative is to make a paragraph of freely-floating words as
  7.1298 -  follows.
  7.1299 +  An alternative is to make a paragraph of freely-floating words as follows.
  7.1300  \<close>
  7.1301  
  7.1302  ML_command \<open>
  7.1303 @@ -1083,60 +1068,60 @@
  7.1304  
  7.1305  section \<open>Exceptions \label{sec:exceptions}\<close>
  7.1306  
  7.1307 -text \<open>The Standard ML semantics of strict functional evaluation
  7.1308 -  together with exceptions is rather well defined, but some delicate
  7.1309 -  points need to be observed to avoid that ML programs go wrong
  7.1310 -  despite static type-checking.  Exceptions in Isabelle/ML are
  7.1311 -  subsequently categorized as follows.\<close>
  7.1312 +text \<open>
  7.1313 +  The Standard ML semantics of strict functional evaluation together with
  7.1314 +  exceptions is rather well defined, but some delicate points need to be
  7.1315 +  observed to avoid that ML programs go wrong despite static type-checking.
  7.1316 +  Exceptions in Isabelle/ML are subsequently categorized as follows.
  7.1317 +\<close>
  7.1318  
  7.1319  paragraph \<open>Regular user errors.\<close>
  7.1320 -text \<open>These are meant to provide informative feedback about malformed input
  7.1321 -  etc.
  7.1322 +text \<open>
  7.1323 +  These are meant to provide informative feedback about malformed input etc.
  7.1324 +
  7.1325 +  The \<^emph>\<open>error\<close> function raises the corresponding @{ML ERROR} exception, with a
  7.1326 +  plain text message as argument. @{ML ERROR} exceptions can be handled
  7.1327 +  internally, in order to be ignored, turned into other exceptions, or
  7.1328 +  cascaded by appending messages. If the corresponding Isabelle/Isar command
  7.1329 +  terminates with an @{ML ERROR} exception state, the system will print the
  7.1330 +  result on the error channel (see \secref{sec:message-channels}).
  7.1331  
  7.1332 -  The \<^emph>\<open>error\<close> function raises the corresponding @{ML ERROR}
  7.1333 -  exception, with a plain text message as argument.  @{ML ERROR}
  7.1334 -  exceptions can be handled internally, in order to be ignored, turned
  7.1335 -  into other exceptions, or cascaded by appending messages.  If the
  7.1336 -  corresponding Isabelle/Isar command terminates with an @{ML ERROR}
  7.1337 -  exception state, the system will print the result on the error
  7.1338 -  channel (see \secref{sec:message-channels}).
  7.1339 +  It is considered bad style to refer to internal function names or values in
  7.1340 +  ML source notation in user error messages. Do not use \<open>@{make_string}\<close> nor
  7.1341 +  \<open>@{here}\<close>!
  7.1342  
  7.1343 -  It is considered bad style to refer to internal function names or
  7.1344 -  values in ML source notation in user error messages.  Do not use
  7.1345 -  \<open>@{make_string}\<close> nor \<open>@{here}\<close>!
  7.1346 -
  7.1347 -  Grammatical correctness of error messages can be improved by
  7.1348 -  \<^emph>\<open>omitting\<close> final punctuation: messages are often concatenated
  7.1349 -  or put into a larger context (e.g.\ augmented with source position).
  7.1350 -  Note that punctuation after formal entities (types, terms, theorems) is
  7.1351 -  particularly prone to user confusion.
  7.1352 +  Grammatical correctness of error messages can be improved by \<^emph>\<open>omitting\<close>
  7.1353 +  final punctuation: messages are often concatenated or put into a larger
  7.1354 +  context (e.g.\ augmented with source position). Note that punctuation after
  7.1355 +  formal entities (types, terms, theorems) is particularly prone to user
  7.1356 +  confusion.
  7.1357  \<close>
  7.1358  
  7.1359  paragraph \<open>Program failures.\<close>
  7.1360 -text \<open>There is a handful of standard exceptions that indicate general failure
  7.1361 +text \<open>
  7.1362 +  There is a handful of standard exceptions that indicate general failure
  7.1363    situations, or failures of core operations on logical entities (types,
  7.1364    terms, theorems, theories, see \chref{ch:logic}).
  7.1365  
  7.1366 -  These exceptions indicate a genuine breakdown of the program, so the
  7.1367 -  main purpose is to determine quickly what has happened where.
  7.1368 -  Traditionally, the (short) exception message would include the name
  7.1369 -  of an ML function, although this is no longer necessary, because the
  7.1370 -  ML runtime system attaches detailed source position stemming from the
  7.1371 -  corresponding @{ML_text raise} keyword.
  7.1372 +  These exceptions indicate a genuine breakdown of the program, so the main
  7.1373 +  purpose is to determine quickly what has happened where. Traditionally, the
  7.1374 +  (short) exception message would include the name of an ML function, although
  7.1375 +  this is no longer necessary, because the ML runtime system attaches detailed
  7.1376 +  source position stemming from the corresponding @{ML_text raise} keyword.
  7.1377  
  7.1378    \<^medskip>
  7.1379 -  User modules can always introduce their own custom
  7.1380 -  exceptions locally, e.g.\ to organize internal failures robustly
  7.1381 -  without overlapping with existing exceptions.  Exceptions that are
  7.1382 -  exposed in module signatures require extra care, though, and should
  7.1383 -  \<^emph>\<open>not\<close> be introduced by default.  Surprise by users of a module
  7.1384 -  can be often minimized by using plain user errors instead.
  7.1385 +  User modules can always introduce their own custom exceptions locally, e.g.\
  7.1386 +  to organize internal failures robustly without overlapping with existing
  7.1387 +  exceptions. Exceptions that are exposed in module signatures require extra
  7.1388 +  care, though, and should \<^emph>\<open>not\<close> be introduced by default. Surprise by users
  7.1389 +  of a module can be often minimized by using plain user errors instead.
  7.1390  \<close>
  7.1391  
  7.1392  paragraph \<open>Interrupts.\<close>
  7.1393 -text \<open>These indicate arbitrary system events: both the ML runtime system and
  7.1394 -  the Isabelle/ML infrastructure signal various exceptional situations by
  7.1395 -  raising the special @{ML Exn.Interrupt} exception in user code.
  7.1396 +text \<open>
  7.1397 +  These indicate arbitrary system events: both the ML runtime system and the
  7.1398 +  Isabelle/ML infrastructure signal various exceptional situations by raising
  7.1399 +  the special @{ML Exn.Interrupt} exception in user code.
  7.1400  
  7.1401    This is the one and only way that physical events can intrude an Isabelle/ML
  7.1402    program. Such an interrupt can mean out-of-memory, stack overflow, timeout,
  7.1403 @@ -1147,20 +1132,18 @@
  7.1404    interrupts unintentionally and thus render the program semantics
  7.1405    ill-defined.
  7.1406  
  7.1407 -  Note that the Interrupt exception dates back to the original SML90
  7.1408 -  language definition.  It was excluded from the SML97 version to
  7.1409 -  avoid its malign impact on ML program semantics, but without
  7.1410 -  providing a viable alternative.  Isabelle/ML recovers physical
  7.1411 -  interruptibility (which is an indispensable tool to implement
  7.1412 -  managed evaluation of command transactions), but requires user code
  7.1413 -  to be strictly transparent wrt.\ interrupts.
  7.1414 +  Note that the Interrupt exception dates back to the original SML90 language
  7.1415 +  definition. It was excluded from the SML97 version to avoid its malign
  7.1416 +  impact on ML program semantics, but without providing a viable alternative.
  7.1417 +  Isabelle/ML recovers physical interruptibility (which is an indispensable
  7.1418 +  tool to implement managed evaluation of command transactions), but requires
  7.1419 +  user code to be strictly transparent wrt.\ interrupts.
  7.1420  
  7.1421    \begin{warn}
  7.1422 -  Isabelle/ML user code needs to terminate promptly on interruption,
  7.1423 -  without guessing at its meaning to the system infrastructure.
  7.1424 -  Temporary handling of interrupts for cleanup of global resources
  7.1425 -  etc.\ needs to be followed immediately by re-raising of the original
  7.1426 -  exception.
  7.1427 +  Isabelle/ML user code needs to terminate promptly on interruption, without
  7.1428 +  guessing at its meaning to the system infrastructure. Temporary handling of
  7.1429 +  interrupts for cleanup of global resources etc.\ needs to be followed
  7.1430 +  immediately by re-raising of the original exception.
  7.1431    \end{warn}
  7.1432  \<close>
  7.1433  
  7.1434 @@ -1175,35 +1158,33 @@
  7.1435    @{index_ML Runtime.exn_trace: "(unit -> 'a) -> 'a"} \\
  7.1436    \end{mldecls}
  7.1437  
  7.1438 -  \<^descr> @{ML try}~\<open>f x\<close> makes the partiality of evaluating
  7.1439 -  \<open>f x\<close> explicit via the option datatype.  Interrupts are
  7.1440 -  \<^emph>\<open>not\<close> handled here, i.e.\ this form serves as safe replacement
  7.1441 -  for the \<^emph>\<open>unsafe\<close> version @{ML_text "(SOME"}~\<open>f
  7.1442 -  x\<close>~@{ML_text "handle _ => NONE)"} that is occasionally seen in
  7.1443 -  books about SML97, but not in Isabelle/ML.
  7.1444 +  \<^descr> @{ML try}~\<open>f x\<close> makes the partiality of evaluating \<open>f x\<close> explicit via the
  7.1445 +  option datatype. Interrupts are \<^emph>\<open>not\<close> handled here, i.e.\ this form serves
  7.1446 +  as safe replacement for the \<^emph>\<open>unsafe\<close> version @{ML_text "(SOME"}~\<open>f
  7.1447 +  x\<close>~@{ML_text "handle _ => NONE)"} that is occasionally seen in books about
  7.1448 +  SML97, but not in Isabelle/ML.
  7.1449  
  7.1450    \<^descr> @{ML can} is similar to @{ML try} with more abstract result.
  7.1451  
  7.1452 -  \<^descr> @{ML ERROR}~\<open>msg\<close> represents user errors; this
  7.1453 -  exception is normally raised indirectly via the @{ML error} function
  7.1454 -  (see \secref{sec:message-channels}).
  7.1455 +  \<^descr> @{ML ERROR}~\<open>msg\<close> represents user errors; this exception is normally
  7.1456 +  raised indirectly via the @{ML error} function (see
  7.1457 +  \secref{sec:message-channels}).
  7.1458  
  7.1459    \<^descr> @{ML Fail}~\<open>msg\<close> represents general program failures.
  7.1460  
  7.1461 -  \<^descr> @{ML Exn.is_interrupt} identifies interrupts robustly, without
  7.1462 -  mentioning concrete exception constructors in user code.  Handled
  7.1463 -  interrupts need to be re-raised promptly!
  7.1464 +  \<^descr> @{ML Exn.is_interrupt} identifies interrupts robustly, without mentioning
  7.1465 +  concrete exception constructors in user code. Handled interrupts need to be
  7.1466 +  re-raised promptly!
  7.1467 +
  7.1468 +  \<^descr> @{ML reraise}~\<open>exn\<close> raises exception \<open>exn\<close> while preserving its implicit
  7.1469 +  position information (if possible, depending on the ML platform).
  7.1470  
  7.1471 -  \<^descr> @{ML reraise}~\<open>exn\<close> raises exception \<open>exn\<close>
  7.1472 -  while preserving its implicit position information (if possible,
  7.1473 -  depending on the ML platform).
  7.1474 +  \<^descr> @{ML Runtime.exn_trace}~@{ML_text "(fn () =>"}~\<open>e\<close>@{ML_text ")"} evaluates
  7.1475 +  expression \<open>e\<close> while printing a full trace of its stack of nested exceptions
  7.1476 +  (if possible, depending on the ML platform).
  7.1477  
  7.1478 -  \<^descr> @{ML Runtime.exn_trace}~@{ML_text "(fn () =>"}~\<open>e\<close>@{ML_text ")"} evaluates expression \<open>e\<close> while printing
  7.1479 -  a full trace of its stack of nested exceptions (if possible,
  7.1480 -  depending on the ML platform).
  7.1481 -
  7.1482 -  Inserting @{ML Runtime.exn_trace} into ML code temporarily is
  7.1483 -  useful for debugging, but not suitable for production code.
  7.1484 +  Inserting @{ML Runtime.exn_trace} into ML code temporarily is useful for
  7.1485 +  debugging, but not suitable for production code.
  7.1486  \<close>
  7.1487  
  7.1488  text %mlantiq \<open>
  7.1489 @@ -1211,19 +1192,19 @@
  7.1490    @{ML_antiquotation_def "assert"} & : & \<open>ML_antiquotation\<close> \\
  7.1491    \end{matharray}
  7.1492  
  7.1493 -  \<^descr> \<open>@{assert}\<close> inlines a function
  7.1494 -  @{ML_type "bool -> unit"} that raises @{ML Fail} if the argument is
  7.1495 -  @{ML false}.  Due to inlining the source position of failed
  7.1496 -  assertions is included in the error output.
  7.1497 +  \<^descr> \<open>@{assert}\<close> inlines a function @{ML_type "bool -> unit"} that raises @{ML
  7.1498 +  Fail} if the argument is @{ML false}. Due to inlining the source position of
  7.1499 +  failed assertions is included in the error output.
  7.1500  \<close>
  7.1501  
  7.1502  
  7.1503  section \<open>Strings of symbols \label{sec:symbols}\<close>
  7.1504  
  7.1505 -text \<open>A \<^emph>\<open>symbol\<close> constitutes the smallest textual unit in Isabelle/ML --- raw
  7.1506 -  ML characters are normally not encountered at all. Isabelle strings consist
  7.1507 -  of a sequence of symbols, represented as a packed string or an exploded list
  7.1508 -  of strings. Each symbol is in itself a small string, which has either one of
  7.1509 +text \<open>
  7.1510 +  A \<^emph>\<open>symbol\<close> constitutes the smallest textual unit in Isabelle/ML --- raw ML
  7.1511 +  characters are normally not encountered at all. Isabelle strings consist of
  7.1512 +  a sequence of symbols, represented as a packed string or an exploded list of
  7.1513 +  strings. Each symbol is in itself a small string, which has either one of
  7.1514    the following forms:
  7.1515  
  7.1516      \<^enum> a single ASCII character ``\<open>c\<close>'', for example ``\<^verbatim>\<open>a\<close>'',
  7.1517 @@ -1276,54 +1257,54 @@
  7.1518    @{index_ML Symbol.decode: "Symbol.symbol -> Symbol.sym"} \\
  7.1519    \end{mldecls}
  7.1520  
  7.1521 -  \<^descr> Type @{ML_type "Symbol.symbol"} represents individual Isabelle
  7.1522 -  symbols.
  7.1523 +  \<^descr> Type @{ML_type "Symbol.symbol"} represents individual Isabelle symbols.
  7.1524  
  7.1525 -  \<^descr> @{ML "Symbol.explode"}~\<open>str\<close> produces a symbol list
  7.1526 -  from the packed form.  This function supersedes @{ML
  7.1527 -  "String.explode"} for virtually all purposes of manipulating text in
  7.1528 -  Isabelle!\<^footnote>\<open>The runtime overhead for exploded strings is
  7.1529 -  mainly that of the list structure: individual symbols that happen to
  7.1530 -  be a singleton string do not require extra memory in Poly/ML.\<close>
  7.1531 +  \<^descr> @{ML "Symbol.explode"}~\<open>str\<close> produces a symbol list from the packed form.
  7.1532 +  This function supersedes @{ML "String.explode"} for virtually all purposes
  7.1533 +  of manipulating text in Isabelle!\<^footnote>\<open>The runtime overhead for exploded strings
  7.1534 +  is mainly that of the list structure: individual symbols that happen to be a
  7.1535 +  singleton string do not require extra memory in Poly/ML.\<close>
  7.1536  
  7.1537    \<^descr> @{ML "Symbol.is_letter"}, @{ML "Symbol.is_digit"}, @{ML
  7.1538 -  "Symbol.is_quasi"}, @{ML "Symbol.is_blank"} classify standard
  7.1539 -  symbols according to fixed syntactic conventions of Isabelle, cf.\
  7.1540 -  @{cite "isabelle-isar-ref"}.
  7.1541 +  "Symbol.is_quasi"}, @{ML "Symbol.is_blank"} classify standard symbols
  7.1542 +  according to fixed syntactic conventions of Isabelle, cf.\ @{cite
  7.1543 +  "isabelle-isar-ref"}.
  7.1544  
  7.1545 -  \<^descr> Type @{ML_type "Symbol.sym"} is a concrete datatype that
  7.1546 -  represents the different kinds of symbols explicitly, with
  7.1547 -  constructors @{ML "Symbol.Char"}, @{ML "Symbol.UTF8"},
  7.1548 -  @{ML "Symbol.Sym"}, @{ML "Symbol.Control"}, @{ML "Symbol.Raw"},
  7.1549 -  @{ML "Symbol.Malformed"}.
  7.1550 +  \<^descr> Type @{ML_type "Symbol.sym"} is a concrete datatype that represents the
  7.1551 +  different kinds of symbols explicitly, with constructors @{ML
  7.1552 +  "Symbol.Char"}, @{ML "Symbol.UTF8"}, @{ML "Symbol.Sym"}, @{ML
  7.1553 +  "Symbol.Control"}, @{ML "Symbol.Raw"}, @{ML "Symbol.Malformed"}.
  7.1554  
  7.1555 -  \<^descr> @{ML "Symbol.decode"} converts the string representation of a
  7.1556 -  symbol into the datatype version.
  7.1557 +  \<^descr> @{ML "Symbol.decode"} converts the string representation of a symbol into
  7.1558 +  the datatype version.
  7.1559  \<close>
  7.1560  
  7.1561  paragraph \<open>Historical note.\<close>
  7.1562 -text \<open>In the original SML90 standard the primitive ML type @{ML_type char} did
  7.1563 -  not exists, and @{ML_text "explode: string -> string list"} produced a list
  7.1564 -  of singleton strings like @{ML "raw_explode: string -> string list"} in
  7.1565 +text \<open>
  7.1566 +  In the original SML90 standard the primitive ML type @{ML_type char} did not
  7.1567 +  exists, and @{ML_text "explode: string -> string list"} produced a list of
  7.1568 +  singleton strings like @{ML "raw_explode: string -> string list"} in
  7.1569    Isabelle/ML today. When SML97 came out, Isabelle did not adopt its somewhat
  7.1570    anachronistic 8-bit or 16-bit characters, but the idea of exploding a string
  7.1571    into a list of small strings was extended to ``symbols'' as explained above.
  7.1572    Thus Isabelle sources can refer to an infinite store of user-defined
  7.1573    symbols, without having to worry about the multitude of Unicode encodings
  7.1574 -  that have emerged over the years.\<close>
  7.1575 +  that have emerged over the years.
  7.1576 +\<close>
  7.1577  
  7.1578  
  7.1579  section \<open>Basic data types\<close>
  7.1580  
  7.1581 -text \<open>The basis library proposal of SML97 needs to be treated with
  7.1582 -  caution.  Many of its operations simply do not fit with important
  7.1583 -  Isabelle/ML conventions (like ``canonical argument order'', see
  7.1584 -  \secref{sec:canonical-argument-order}), others cause problems with
  7.1585 -  the parallel evaluation model of Isabelle/ML (such as @{ML
  7.1586 -  TextIO.print} or @{ML OS.Process.system}).
  7.1587 +text \<open>
  7.1588 +  The basis library proposal of SML97 needs to be treated with caution. Many
  7.1589 +  of its operations simply do not fit with important Isabelle/ML conventions
  7.1590 +  (like ``canonical argument order'', see
  7.1591 +  \secref{sec:canonical-argument-order}), others cause problems with the
  7.1592 +  parallel evaluation model of Isabelle/ML (such as @{ML TextIO.print} or @{ML
  7.1593 +  OS.Process.system}).
  7.1594  
  7.1595 -  Subsequently we give a brief overview of important operations on
  7.1596 -  basic ML data types.
  7.1597 +  Subsequently we give a brief overview of important operations on basic ML
  7.1598 +  data types.
  7.1599  \<close>
  7.1600  
  7.1601  
  7.1602 @@ -1334,9 +1315,8 @@
  7.1603    @{index_ML_type char} \\
  7.1604    \end{mldecls}
  7.1605  
  7.1606 -  \<^descr> Type @{ML_type char} is \<^emph>\<open>not\<close> used.  The smallest textual
  7.1607 -  unit in Isabelle is represented as a ``symbol'' (see
  7.1608 -  \secref{sec:symbols}).
  7.1609 +  \<^descr> Type @{ML_type char} is \<^emph>\<open>not\<close> used. The smallest textual unit in Isabelle
  7.1610 +  is represented as a ``symbol'' (see \secref{sec:symbols}).
  7.1611  \<close>
  7.1612  
  7.1613  
  7.1614 @@ -1347,29 +1327,29 @@
  7.1615    @{index_ML_type string} \\
  7.1616    \end{mldecls}
  7.1617  
  7.1618 -  \<^descr> Type @{ML_type string} represents immutable vectors of 8-bit
  7.1619 -  characters.  There are operations in SML to convert back and forth
  7.1620 -  to actual byte vectors, which are seldom used.
  7.1621 +  \<^descr> Type @{ML_type string} represents immutable vectors of 8-bit characters.
  7.1622 +  There are operations in SML to convert back and forth to actual byte
  7.1623 +  vectors, which are seldom used.
  7.1624  
  7.1625    This historically important raw text representation is used for
  7.1626 -  Isabelle-specific purposes with the following implicit substructures
  7.1627 -  packed into the string content:
  7.1628 +  Isabelle-specific purposes with the following implicit substructures packed
  7.1629 +  into the string content:
  7.1630  
  7.1631 -    \<^enum> sequence of Isabelle symbols (see also \secref{sec:symbols}),
  7.1632 -    with @{ML Symbol.explode} as key operation;
  7.1633 +    \<^enum> sequence of Isabelle symbols (see also \secref{sec:symbols}), with @{ML
  7.1634 +    Symbol.explode} as key operation;
  7.1635    
  7.1636 -    \<^enum> XML tree structure via YXML (see also @{cite "isabelle-system"}),
  7.1637 -    with @{ML YXML.parse_body} as key operation.
  7.1638 +    \<^enum> XML tree structure via YXML (see also @{cite "isabelle-system"}), with
  7.1639 +    @{ML YXML.parse_body} as key operation.
  7.1640  
  7.1641    Note that Isabelle/ML string literals may refer Isabelle symbols like
  7.1642 -  ``\<^verbatim>\<open>\<alpha>\<close>'' natively, \<^emph>\<open>without\<close> escaping the backslash. This is a
  7.1643 -  consequence of Isabelle treating all source text as strings of symbols,
  7.1644 -  instead of raw characters.
  7.1645 +  ``\<^verbatim>\<open>\<alpha>\<close>'' natively, \<^emph>\<open>without\<close> escaping the backslash. This is a consequence
  7.1646 +  of Isabelle treating all source text as strings of symbols, instead of raw
  7.1647 +  characters.
  7.1648  \<close>
  7.1649  
  7.1650 -text %mlex \<open>The subsequent example illustrates the difference of
  7.1651 -  physical addressing of bytes versus logical addressing of symbols in
  7.1652 -  Isabelle strings.
  7.1653 +text %mlex \<open>
  7.1654 +  The subsequent example illustrates the difference of physical addressing of
  7.1655 +  bytes versus logical addressing of symbols in Isabelle strings.
  7.1656  \<close>
  7.1657  
  7.1658  ML_val \<open>
  7.1659 @@ -1379,12 +1359,14 @@
  7.1660    @{assert} (size s = 4);
  7.1661  \<close>
  7.1662  
  7.1663 -text \<open>Note that in Unicode renderings of the symbol \<open>\<A>\<close>,
  7.1664 -  variations of encodings like UTF-8 or UTF-16 pose delicate questions
  7.1665 -  about the multi-byte representations of its codepoint, which is outside
  7.1666 -  of the 16-bit address space of the original Unicode standard from
  7.1667 -  the 1990-ies.  In Isabelle/ML it is just ``\<^verbatim>\<open>\<A>\<close>''
  7.1668 -  literally, using plain ASCII characters beyond any doubts.\<close>
  7.1669 +text \<open>
  7.1670 +  Note that in Unicode renderings of the symbol \<open>\<A>\<close>, variations of encodings
  7.1671 +  like UTF-8 or UTF-16 pose delicate questions about the multi-byte
  7.1672 +  representations of its codepoint, which is outside of the 16-bit address
  7.1673 +  space of the original Unicode standard from the 1990-ies. In Isabelle/ML it
  7.1674 +  is just ``\<^verbatim>\<open>\<A>\<close>'' literally, using plain ASCII characters beyond any
  7.1675 +  doubts.
  7.1676 +\<close>
  7.1677  
  7.1678  
  7.1679  subsection \<open>Integers\<close>
  7.1680 @@ -1394,19 +1376,18 @@
  7.1681    @{index_ML_type int} \\
  7.1682    \end{mldecls}
  7.1683  
  7.1684 -  \<^descr> Type @{ML_type int} represents regular mathematical integers, which
  7.1685 -  are \<^emph>\<open>unbounded\<close>. Overflow is treated properly, but should never happen
  7.1686 -  in practice.\<^footnote>\<open>The size limit for integer bit patterns in memory is
  7.1687 -  64\,MB for 32-bit Poly/ML, and much higher for 64-bit systems.\<close> This works
  7.1688 -  uniformly for all supported ML platforms (Poly/ML and SML/NJ).
  7.1689 +  \<^descr> Type @{ML_type int} represents regular mathematical integers, which are
  7.1690 +  \<^emph>\<open>unbounded\<close>. Overflow is treated properly, but should never happen in
  7.1691 +  practice.\<^footnote>\<open>The size limit for integer bit patterns in memory is 64\,MB for
  7.1692 +  32-bit Poly/ML, and much higher for 64-bit systems.\<close> This works uniformly
  7.1693 +  for all supported ML platforms (Poly/ML and SML/NJ).
  7.1694  
  7.1695 -  Literal integers in ML text are forced to be of this one true
  7.1696 -  integer type --- adhoc overloading of SML97 is disabled.
  7.1697 +  Literal integers in ML text are forced to be of this one true integer type
  7.1698 +  --- adhoc overloading of SML97 is disabled.
  7.1699  
  7.1700    Structure @{ML_structure IntInf} of SML97 is obsolete and superseded by
  7.1701 -  @{ML_structure Int}.  Structure @{ML_structure Integer} in @{file
  7.1702 -  "~~/src/Pure/General/integer.ML"} provides some additional
  7.1703 -  operations.
  7.1704 +  @{ML_structure Int}. Structure @{ML_structure Integer} in @{file
  7.1705 +  "~~/src/Pure/General/integer.ML"} provides some additional operations.
  7.1706  \<close>
  7.1707  
  7.1708  
  7.1709 @@ -1418,14 +1399,14 @@
  7.1710    @{index_ML seconds: "real -> Time.time"} \\
  7.1711    \end{mldecls}
  7.1712  
  7.1713 -  \<^descr> Type @{ML_type Time.time} represents time abstractly according
  7.1714 -  to the SML97 basis library definition.  This is adequate for
  7.1715 -  internal ML operations, but awkward in concrete time specifications.
  7.1716 +  \<^descr> Type @{ML_type Time.time} represents time abstractly according to the
  7.1717 +  SML97 basis library definition. This is adequate for internal ML operations,
  7.1718 +  but awkward in concrete time specifications.
  7.1719  
  7.1720 -  \<^descr> @{ML seconds}~\<open>s\<close> turns the concrete scalar \<open>s\<close> (measured in seconds) into an abstract time value.  Floating
  7.1721 -  point numbers are easy to use as configuration options in the
  7.1722 -  context (see \secref{sec:config-options}) or system options that
  7.1723 -  are maintained externally.
  7.1724 +  \<^descr> @{ML seconds}~\<open>s\<close> turns the concrete scalar \<open>s\<close> (measured in seconds) into
  7.1725 +  an abstract time value. Floating point numbers are easy to use as
  7.1726 +  configuration options in the context (see \secref{sec:config-options}) or
  7.1727 +  system options that are maintained externally.
  7.1728  \<close>
  7.1729  
  7.1730  
  7.1731 @@ -1443,18 +1424,21 @@
  7.1732    \end{mldecls}
  7.1733  \<close>
  7.1734  
  7.1735 -text \<open>Apart from @{ML Option.map} most other operations defined in
  7.1736 -  structure @{ML_structure Option} are alien to Isabelle/ML and never
  7.1737 -  used.  The operations shown above are defined in @{file
  7.1738 -  "~~/src/Pure/General/basics.ML"}.\<close>
  7.1739 +text \<open>
  7.1740 +  Apart from @{ML Option.map} most other operations defined in structure
  7.1741 +  @{ML_structure Option} are alien to Isabelle/ML and never used. The
  7.1742 +  operations shown above are defined in @{file
  7.1743 +  "~~/src/Pure/General/basics.ML"}.
  7.1744 +\<close>
  7.1745  
  7.1746  
  7.1747  subsection \<open>Lists\<close>
  7.1748  
  7.1749 -text \<open>Lists are ubiquitous in ML as simple and light-weight
  7.1750 -  ``collections'' for many everyday programming tasks.  Isabelle/ML
  7.1751 -  provides important additions and improvements over operations that
  7.1752 -  are predefined in the SML97 library.\<close>
  7.1753 +text \<open>
  7.1754 +  Lists are ubiquitous in ML as simple and light-weight ``collections'' for
  7.1755 +  many everyday programming tasks. Isabelle/ML provides important additions
  7.1756 +  and improvements over operations that are predefined in the SML97 library.
  7.1757 +\<close>
  7.1758  
  7.1759  text %mlref \<open>
  7.1760    \begin{mldecls}
  7.1761 @@ -1467,30 +1451,28 @@
  7.1762  
  7.1763    \<^descr> @{ML cons}~\<open>x xs\<close> evaluates to \<open>x :: xs\<close>.
  7.1764  
  7.1765 -  Tupled infix operators are a historical accident in Standard ML.
  7.1766 -  The curried @{ML cons} amends this, but it should be only used when
  7.1767 -  partial application is required.
  7.1768 +  Tupled infix operators are a historical accident in Standard ML. The curried
  7.1769 +  @{ML cons} amends this, but it should be only used when partial application
  7.1770 +  is required.
  7.1771  
  7.1772 -  \<^descr> @{ML member}, @{ML insert}, @{ML remove}, @{ML update} treat
  7.1773 -  lists as a set-like container that maintains the order of elements.
  7.1774 -  See @{file "~~/src/Pure/library.ML"} for the full specifications
  7.1775 -  (written in ML).  There are some further derived operations like
  7.1776 -  @{ML union} or @{ML inter}.
  7.1777 +  \<^descr> @{ML member}, @{ML insert}, @{ML remove}, @{ML update} treat lists as a
  7.1778 +  set-like container that maintains the order of elements. See @{file
  7.1779 +  "~~/src/Pure/library.ML"} for the full specifications (written in ML). There
  7.1780 +  are some further derived operations like @{ML union} or @{ML inter}.
  7.1781  
  7.1782 -  Note that @{ML insert} is conservative about elements that are
  7.1783 -  already a @{ML member} of the list, while @{ML update} ensures that
  7.1784 -  the latest entry is always put in front.  The latter discipline is
  7.1785 -  often more appropriate in declarations of context data
  7.1786 -  (\secref{sec:context-data}) that are issued by the user in Isar
  7.1787 -  source: later declarations take precedence over earlier ones.
  7.1788 -\<close>
  7.1789 +  Note that @{ML insert} is conservative about elements that are already a
  7.1790 +  @{ML member} of the list, while @{ML update} ensures that the latest entry
  7.1791 +  is always put in front. The latter discipline is often more appropriate in
  7.1792 +  declarations of context data (\secref{sec:context-data}) that are issued by
  7.1793 +  the user in Isar source: later declarations take precedence over earlier
  7.1794 +  ones. \<close>
  7.1795  
  7.1796 -text %mlex \<open>Using canonical @{ML fold} together with @{ML cons} (or
  7.1797 -  similar standard operations) alternates the orientation of data.
  7.1798 -  The is quite natural and should not be altered forcible by inserting
  7.1799 -  extra applications of @{ML rev}.  The alternative @{ML fold_rev} can
  7.1800 -  be used in the few situations, where alternation should be
  7.1801 -  prevented.
  7.1802 +text %mlex \<open>
  7.1803 +  Using canonical @{ML fold} together with @{ML cons} (or similar standard
  7.1804 +  operations) alternates the orientation of data. The is quite natural and
  7.1805 +  should not be altered forcible by inserting extra applications of @{ML rev}.
  7.1806 +  The alternative @{ML fold_rev} can be used in the few situations, where
  7.1807 +  alternation should be prevented.
  7.1808  \<close>
  7.1809  
  7.1810  ML_val \<open>
  7.1811 @@ -1503,31 +1485,33 @@
  7.1812    @{assert} (list2 = items);
  7.1813  \<close>
  7.1814  
  7.1815 -text \<open>The subsequent example demonstrates how to \<^emph>\<open>merge\<close> two
  7.1816 -  lists in a natural way.\<close>
  7.1817 +text \<open>
  7.1818 +  The subsequent example demonstrates how to \<^emph>\<open>merge\<close> two lists in a natural
  7.1819 +  way.
  7.1820 +\<close>
  7.1821  
  7.1822  ML_val \<open>
  7.1823    fun merge_lists eq (xs, ys) = fold_rev (insert eq) ys xs;
  7.1824  \<close>
  7.1825  
  7.1826 -text \<open>Here the first list is treated conservatively: only the new
  7.1827 -  elements from the second list are inserted.  The inside-out order of
  7.1828 -  insertion via @{ML fold_rev} attempts to preserve the order of
  7.1829 -  elements in the result.
  7.1830 +text \<open>
  7.1831 +  Here the first list is treated conservatively: only the new elements from
  7.1832 +  the second list are inserted. The inside-out order of insertion via @{ML
  7.1833 +  fold_rev} attempts to preserve the order of elements in the result.
  7.1834  
  7.1835    This way of merging lists is typical for context data
  7.1836 -  (\secref{sec:context-data}).  See also @{ML merge} as defined in
  7.1837 -  @{file "~~/src/Pure/library.ML"}.
  7.1838 +  (\secref{sec:context-data}). See also @{ML merge} as defined in @{file
  7.1839 +  "~~/src/Pure/library.ML"}.
  7.1840  \<close>
  7.1841  
  7.1842  
  7.1843  subsection \<open>Association lists\<close>
  7.1844  
  7.1845 -text \<open>The operations for association lists interpret a concrete list
  7.1846 -  of pairs as a finite function from keys to values.  Redundant
  7.1847 -  representations with multiple occurrences of the same key are
  7.1848 -  implicitly normalized: lookup and update only take the first
  7.1849 -  occurrence into account.
  7.1850 +text \<open>
  7.1851 +  The operations for association lists interpret a concrete list of pairs as a
  7.1852 +  finite function from keys to values. Redundant representations with multiple
  7.1853 +  occurrences of the same key are implicitly normalized: lookup and update
  7.1854 +  only take the first occurrence into account.
  7.1855  \<close>
  7.1856  
  7.1857  text \<open>
  7.1858 @@ -1537,20 +1521,18 @@
  7.1859    @{index_ML AList.update: "('a * 'a -> bool) -> 'a * 'b -> ('a * 'b) list -> ('a * 'b) list"} \\
  7.1860    \end{mldecls}
  7.1861  
  7.1862 -  \<^descr> @{ML AList.lookup}, @{ML AList.defined}, @{ML AList.update}
  7.1863 -  implement the main ``framework operations'' for mappings in
  7.1864 -  Isabelle/ML, following standard conventions for their names and
  7.1865 -  types.
  7.1866 +  \<^descr> @{ML AList.lookup}, @{ML AList.defined}, @{ML AList.update} implement the
  7.1867 +  main ``framework operations'' for mappings in Isabelle/ML, following
  7.1868 +  standard conventions for their names and types.
  7.1869  
  7.1870 -  Note that a function called \<^verbatim>\<open>lookup\<close> is obliged to express its
  7.1871 -  partiality via an explicit option element.  There is no choice to
  7.1872 -  raise an exception, without changing the name to something like
  7.1873 -  \<open>the_element\<close> or \<open>get\<close>.
  7.1874 +  Note that a function called \<^verbatim>\<open>lookup\<close> is obliged to express its partiality
  7.1875 +  via an explicit option element. There is no choice to raise an exception,
  7.1876 +  without changing the name to something like \<open>the_element\<close> or \<open>get\<close>.
  7.1877  
  7.1878 -  The \<open>defined\<close> operation is essentially a contraction of @{ML
  7.1879 -  is_some} and \<^verbatim>\<open>lookup\<close>, but this is sufficiently frequent to
  7.1880 -  justify its independent existence.  This also gives the
  7.1881 -  implementation some opportunity for peep-hole optimization.
  7.1882 +  The \<open>defined\<close> operation is essentially a contraction of @{ML is_some} and
  7.1883 +  \<^verbatim>\<open>lookup\<close>, but this is sufficiently frequent to justify its independent
  7.1884 +  existence. This also gives the implementation some opportunity for peep-hole
  7.1885 +  optimization.
  7.1886  
  7.1887  
  7.1888    Association lists are adequate as simple implementation of finite mappings
  7.1889 @@ -1571,18 +1553,18 @@
  7.1890    \end{mldecls}
  7.1891  \<close>
  7.1892  
  7.1893 -text \<open>Due to ubiquitous parallelism in Isabelle/ML (see also
  7.1894 -  \secref{sec:multi-threading}), the mutable reference cells of
  7.1895 -  Standard ML are notorious for causing problems.  In a highly
  7.1896 -  parallel system, both correctness \<^emph>\<open>and\<close> performance are easily
  7.1897 -  degraded when using mutable data.
  7.1898 +text \<open>
  7.1899 +  Due to ubiquitous parallelism in Isabelle/ML (see also
  7.1900 +  \secref{sec:multi-threading}), the mutable reference cells of Standard ML
  7.1901 +  are notorious for causing problems. In a highly parallel system, both
  7.1902 +  correctness \<^emph>\<open>and\<close> performance are easily degraded when using mutable data.
  7.1903  
  7.1904 -  The unwieldy name of @{ML Unsynchronized.ref} for the constructor
  7.1905 -  for references in Isabelle/ML emphasizes the inconveniences caused by
  7.1906 -  mutability.  Existing operations @{ML "!"}  and @{ML_op ":="} are
  7.1907 -  unchanged, but should be used with special precautions, say in a
  7.1908 -  strictly local situation that is guaranteed to be restricted to
  7.1909 -  sequential evaluation --- now and in the future.
  7.1910 +  The unwieldy name of @{ML Unsynchronized.ref} for the constructor for
  7.1911 +  references in Isabelle/ML emphasizes the inconveniences caused by
  7.1912 +  mutability. Existing operations @{ML "!"} and @{ML_op ":="} are unchanged,
  7.1913 +  but should be used with special precautions, say in a strictly local
  7.1914 +  situation that is guaranteed to be restricted to sequential evaluation ---
  7.1915 +  now and in the future.
  7.1916  
  7.1917    \begin{warn}
  7.1918    Never @{ML_text "open Unsynchronized"}, not even in a local scope!
  7.1919 @@ -1593,62 +1575,58 @@
  7.1920  
  7.1921  section \<open>Thread-safe programming \label{sec:multi-threading}\<close>
  7.1922  
  7.1923 -text \<open>Multi-threaded execution has become an everyday reality in
  7.1924 -  Isabelle since Poly/ML 5.2.1 and Isabelle2008.  Isabelle/ML provides
  7.1925 -  implicit and explicit parallelism by default, and there is no way
  7.1926 -  for user-space tools to ``opt out''.  ML programs that are purely
  7.1927 -  functional, output messages only via the official channels
  7.1928 -  (\secref{sec:message-channels}), and do not intercept interrupts
  7.1929 -  (\secref{sec:exceptions}) can participate in the multi-threaded
  7.1930 +text \<open>
  7.1931 +  Multi-threaded execution has become an everyday reality in Isabelle since
  7.1932 +  Poly/ML 5.2.1 and Isabelle2008. Isabelle/ML provides implicit and explicit
  7.1933 +  parallelism by default, and there is no way for user-space tools to ``opt
  7.1934 +  out''. ML programs that are purely functional, output messages only via the
  7.1935 +  official channels (\secref{sec:message-channels}), and do not intercept
  7.1936 +  interrupts (\secref{sec:exceptions}) can participate in the multi-threaded
  7.1937    environment immediately without further ado.
  7.1938  
  7.1939 -  More ambitious tools with more fine-grained interaction with the
  7.1940 -  environment need to observe the principles explained below.
  7.1941 +  More ambitious tools with more fine-grained interaction with the environment
  7.1942 +  need to observe the principles explained below.
  7.1943  \<close>
  7.1944  
  7.1945  
  7.1946  subsection \<open>Multi-threading with shared memory\<close>
  7.1947  
  7.1948 -text \<open>Multiple threads help to organize advanced operations of the
  7.1949 -  system, such as real-time conditions on command transactions,
  7.1950 -  sub-components with explicit communication, general asynchronous
  7.1951 -  interaction etc.  Moreover, parallel evaluation is a prerequisite to
  7.1952 -  make adequate use of the CPU resources that are available on
  7.1953 -  multi-core systems.\<^footnote>\<open>Multi-core computing does not mean that
  7.1954 -  there are ``spare cycles'' to be wasted.  It means that the
  7.1955 -  continued exponential speedup of CPU performance due to ``Moore's
  7.1956 -  Law'' follows different rules: clock frequency has reached its peak
  7.1957 -  around 2005, and applications need to be parallelized in order to
  7.1958 -  avoid a perceived loss of performance.  See also
  7.1959 -  @{cite "Sutter:2005"}.\<close>
  7.1960 +text \<open>
  7.1961 +  Multiple threads help to organize advanced operations of the system, such as
  7.1962 +  real-time conditions on command transactions, sub-components with explicit
  7.1963 +  communication, general asynchronous interaction etc. Moreover, parallel
  7.1964 +  evaluation is a prerequisite to make adequate use of the CPU resources that
  7.1965 +  are available on multi-core systems.\<^footnote>\<open>Multi-core computing does not mean
  7.1966 +  that there are ``spare cycles'' to be wasted. It means that the continued
  7.1967 +  exponential speedup of CPU performance due to ``Moore's Law'' follows
  7.1968 +  different rules: clock frequency has reached its peak around 2005, and
  7.1969 +  applications need to be parallelized in order to avoid a perceived loss of
  7.1970 +  performance. See also @{cite "Sutter:2005"}.\<close>
  7.1971  
  7.1972    Isabelle/Isar exploits the inherent structure of theories and proofs to
  7.1973 -  support \<^emph>\<open>implicit parallelism\<close> to a large extent. LCF-style theorem
  7.1974 -  proving provides almost ideal conditions for that, see also
  7.1975 -  @{cite "Wenzel:2009"}. This means, significant parts of theory and proof
  7.1976 -  checking is parallelized by default. In Isabelle2013, a maximum
  7.1977 -  speedup-factor of 3.5 on 4 cores and 6.5 on 8 cores can be expected
  7.1978 -  @{cite "Wenzel:2013:ITP"}.
  7.1979 +  support \<^emph>\<open>implicit parallelism\<close> to a large extent. LCF-style theorem proving
  7.1980 +  provides almost ideal conditions for that, see also @{cite "Wenzel:2009"}.
  7.1981 +  This means, significant parts of theory and proof checking is parallelized
  7.1982 +  by default. In Isabelle2013, a maximum speedup-factor of 3.5 on 4 cores and
  7.1983 +  6.5 on 8 cores can be expected @{cite "Wenzel:2013:ITP"}.
  7.1984  
  7.1985    \<^medskip>
  7.1986 -  ML threads lack the memory protection of separate
  7.1987 -  processes, and operate concurrently on shared heap memory.  This has
  7.1988 -  the advantage that results of independent computations are directly
  7.1989 -  available to other threads: abstract values can be passed without
  7.1990 -  copying or awkward serialization that is typically required for
  7.1991 -  separate processes.
  7.1992 +  ML threads lack the memory protection of separate processes, and operate
  7.1993 +  concurrently on shared heap memory. This has the advantage that results of
  7.1994 +  independent computations are directly available to other threads: abstract
  7.1995 +  values can be passed without copying or awkward serialization that is
  7.1996 +  typically required for separate processes.
  7.1997  
  7.1998 -  To make shared-memory multi-threading work robustly and efficiently,
  7.1999 -  some programming guidelines need to be observed.  While the ML
  7.2000 -  system is responsible to maintain basic integrity of the
  7.2001 -  representation of ML values in memory, the application programmer
  7.2002 -  needs to ensure that multi-threaded execution does not break the
  7.2003 -  intended semantics.
  7.2004 +  To make shared-memory multi-threading work robustly and efficiently, some
  7.2005 +  programming guidelines need to be observed. While the ML system is
  7.2006 +  responsible to maintain basic integrity of the representation of ML values
  7.2007 +  in memory, the application programmer needs to ensure that multi-threaded
  7.2008 +  execution does not break the intended semantics.
  7.2009  
  7.2010    \begin{warn}
  7.2011 -  To participate in implicit parallelism, tools need to be
  7.2012 -  thread-safe.  A single ill-behaved tool can affect the stability and
  7.2013 -  performance of the whole system.
  7.2014 +  To participate in implicit parallelism, tools need to be thread-safe. A
  7.2015 +  single ill-behaved tool can affect the stability and performance of the
  7.2016 +  whole system.
  7.2017    \end{warn}
  7.2018  
  7.2019    Apart from observing the principles of thread-safeness passively, advanced
  7.2020 @@ -1656,76 +1634,69 @@
  7.2021    functions for parallel list operations (\secref{sec:parlist}).
  7.2022  
  7.2023    \begin{warn}
  7.2024 -  Parallel computing resources are managed centrally by the
  7.2025 -  Isabelle/ML infrastructure.  User programs should not fork their own
  7.2026 -  ML threads to perform heavy computations.
  7.2027 +  Parallel computing resources are managed centrally by the Isabelle/ML
  7.2028 +  infrastructure. User programs should not fork their own ML threads to
  7.2029 +  perform heavy computations.
  7.2030    \end{warn}
  7.2031  \<close>
  7.2032  
  7.2033  
  7.2034  subsection \<open>Critical shared resources\<close>
  7.2035  
  7.2036 -text \<open>Thread-safeness is mainly concerned about concurrent
  7.2037 -  read/write access to shared resources, which are outside the purely
  7.2038 -  functional world of ML.  This covers the following in particular.
  7.2039 -
  7.2040 -  \<^item> Global references (or arrays), i.e.\ mutable memory cells that
  7.2041 -  persist over several invocations of associated
  7.2042 -  operations.\<^footnote>\<open>This is independent of the visibility of such
  7.2043 -  mutable values in the toplevel scope.\<close>
  7.2044 +text \<open>
  7.2045 +  Thread-safeness is mainly concerned about concurrent read/write access to
  7.2046 +  shared resources, which are outside the purely functional world of ML. This
  7.2047 +  covers the following in particular.
  7.2048  
  7.2049 -  \<^item> Global state of the running Isabelle/ML process, i.e.\ raw I/O
  7.2050 -  channels, environment variables, current working directory.
  7.2051 -
  7.2052 -  \<^item> Writable resources in the file-system that are shared among
  7.2053 -  different threads or external processes.
  7.2054 +    \<^item> Global references (or arrays), i.e.\ mutable memory cells that persist
  7.2055 +    over several invocations of associated operations.\<^footnote>\<open>This is independent of
  7.2056 +    the visibility of such mutable values in the toplevel scope.\<close>
  7.2057  
  7.2058 +    \<^item> Global state of the running Isabelle/ML process, i.e.\ raw I/O channels,
  7.2059 +    environment variables, current working directory.
  7.2060  
  7.2061 -  Isabelle/ML provides various mechanisms to avoid critical shared
  7.2062 -  resources in most situations.  As last resort there are some
  7.2063 -  mechanisms for explicit synchronization.  The following guidelines
  7.2064 -  help to make Isabelle/ML programs work smoothly in a concurrent
  7.2065 -  environment.
  7.2066 +    \<^item> Writable resources in the file-system that are shared among different
  7.2067 +    threads or external processes.
  7.2068  
  7.2069 -  \<^item> Avoid global references altogether.  Isabelle/Isar maintains a
  7.2070 -  uniform context that incorporates arbitrary data declared by user
  7.2071 -  programs (\secref{sec:context-data}).  This context is passed as
  7.2072 -  plain value and user tools can get/map their own data in a purely
  7.2073 -  functional manner.  Configuration options within the context
  7.2074 -  (\secref{sec:config-options}) provide simple drop-in replacements
  7.2075 -  for historic reference variables.
  7.2076 +  Isabelle/ML provides various mechanisms to avoid critical shared resources
  7.2077 +  in most situations. As last resort there are some mechanisms for explicit
  7.2078 +  synchronization. The following guidelines help to make Isabelle/ML programs
  7.2079 +  work smoothly in a concurrent environment.
  7.2080 +
  7.2081 +  \<^item> Avoid global references altogether. Isabelle/Isar maintains a uniform
  7.2082 +  context that incorporates arbitrary data declared by user programs
  7.2083 +  (\secref{sec:context-data}). This context is passed as plain value and user
  7.2084 +  tools can get/map their own data in a purely functional manner.
  7.2085 +  Configuration options within the context (\secref{sec:config-options})
  7.2086 +  provide simple drop-in replacements for historic reference variables.
  7.2087  
  7.2088 -  \<^item> Keep components with local state information re-entrant.
  7.2089 -  Instead of poking initial values into (private) global references, a
  7.2090 -  new state record can be created on each invocation, and passed
  7.2091 -  through any auxiliary functions of the component.  The state record
  7.2092 -  contain mutable references in special situations, without requiring any
  7.2093 -  synchronization, as long as each invocation gets its own copy and the
  7.2094 -  tool itself is single-threaded.
  7.2095 +  \<^item> Keep components with local state information re-entrant. Instead of poking
  7.2096 +  initial values into (private) global references, a new state record can be
  7.2097 +  created on each invocation, and passed through any auxiliary functions of
  7.2098 +  the component. The state record contain mutable references in special
  7.2099 +  situations, without requiring any synchronization, as long as each
  7.2100 +  invocation gets its own copy and the tool itself is single-threaded.
  7.2101  
  7.2102 -  \<^item> Avoid raw output on \<open>stdout\<close> or \<open>stderr\<close>.  The
  7.2103 -  Poly/ML library is thread-safe for each individual output operation,
  7.2104 -  but the ordering of parallel invocations is arbitrary.  This means
  7.2105 -  raw output will appear on some system console with unpredictable
  7.2106 -  interleaving of atomic chunks.
  7.2107 +  \<^item> Avoid raw output on \<open>stdout\<close> or \<open>stderr\<close>. The Poly/ML library is
  7.2108 +  thread-safe for each individual output operation, but the ordering of
  7.2109 +  parallel invocations is arbitrary. This means raw output will appear on some
  7.2110 +  system console with unpredictable interleaving of atomic chunks.
  7.2111  
  7.2112    Note that this does not affect regular message output channels
  7.2113 -  (\secref{sec:message-channels}).  An official message id is associated
  7.2114 -  with the command transaction from where it originates, independently
  7.2115 -  of other transactions.  This means each running Isar command has
  7.2116 -  effectively its own set of message channels, and interleaving can
  7.2117 -  only happen when commands use parallelism internally (and only at
  7.2118 -  message boundaries).
  7.2119 +  (\secref{sec:message-channels}). An official message id is associated with
  7.2120 +  the command transaction from where it originates, independently of other
  7.2121 +  transactions. This means each running Isar command has effectively its own
  7.2122 +  set of message channels, and interleaving can only happen when commands use
  7.2123 +  parallelism internally (and only at message boundaries).
  7.2124  
  7.2125 -  \<^item> Treat environment variables and the current working directory
  7.2126 -  of the running process as read-only.
  7.2127 +  \<^item> Treat environment variables and the current working directory of the
  7.2128 +  running process as read-only.
  7.2129  
  7.2130 -  \<^item> Restrict writing to the file-system to unique temporary files.
  7.2131 -  Isabelle already provides a temporary directory that is unique for
  7.2132 -  the running process, and there is a centralized source of unique
  7.2133 -  serial numbers in Isabelle/ML.  Thus temporary files that are passed
  7.2134 -  to to some external process will be always disjoint, and thus
  7.2135 -  thread-safe.
  7.2136 +  \<^item> Restrict writing to the file-system to unique temporary files. Isabelle
  7.2137 +  already provides a temporary directory that is unique for the running
  7.2138 +  process, and there is a centralized source of unique serial numbers in
  7.2139 +  Isabelle/ML. Thus temporary files that are passed to to some external
  7.2140 +  process will be always disjoint, and thus thread-safe.
  7.2141  \<close>
  7.2142  
  7.2143  text %mlref \<open>
  7.2144 @@ -1734,16 +1705,15 @@
  7.2145    @{index_ML serial_string: "unit -> string"} \\
  7.2146    \end{mldecls}
  7.2147  
  7.2148 -  \<^descr> @{ML File.tmp_path}~\<open>path\<close> relocates the base
  7.2149 -  component of \<open>path\<close> into the unique temporary directory of
  7.2150 -  the running Isabelle/ML process.
  7.2151 +  \<^descr> @{ML File.tmp_path}~\<open>path\<close> relocates the base component of \<open>path\<close> into the
  7.2152 +  unique temporary directory of the running Isabelle/ML process.
  7.2153  
  7.2154 -  \<^descr> @{ML serial_string}~\<open>()\<close> creates a new serial number
  7.2155 -  that is unique over the runtime of the Isabelle/ML process.
  7.2156 +  \<^descr> @{ML serial_string}~\<open>()\<close> creates a new serial number that is unique over
  7.2157 +  the runtime of the Isabelle/ML process.
  7.2158  \<close>
  7.2159  
  7.2160 -text %mlex \<open>The following example shows how to create unique
  7.2161 -  temporary file names.
  7.2162 +text %mlex \<open>
  7.2163 +  The following example shows how to create unique temporary file names.
  7.2164  \<close>
  7.2165  
  7.2166  ML_val \<open>
  7.2167 @@ -1755,7 +1725,8 @@
  7.2168  
  7.2169  subsection \<open>Explicit synchronization\<close>
  7.2170  
  7.2171 -text \<open>Isabelle/ML provides explicit synchronization for mutable variables over
  7.2172 +text \<open>
  7.2173 +  Isabelle/ML provides explicit synchronization for mutable variables over
  7.2174    immutable data, which may be updated atomically and exclusively. This
  7.2175    addresses the rare situations where mutable shared resources are really
  7.2176    required. Synchronization in Isabelle/ML is based on primitives of Poly/ML,
  7.2177 @@ -1763,11 +1734,12 @@
  7.2178    Isabelle environment. User code should not break this abstraction, but stay
  7.2179    within the confines of concurrent Isabelle/ML.
  7.2180  
  7.2181 -  A \<^emph>\<open>synchronized variable\<close> is an explicit state component associated
  7.2182 -  with mechanisms for locking and signaling. There are operations to await a
  7.2183 +  A \<^emph>\<open>synchronized variable\<close> is an explicit state component associated with
  7.2184 +  mechanisms for locking and signaling. There are operations to await a
  7.2185    condition, change the state, and signal the change to all other waiting
  7.2186    threads. Synchronized access to the state variable is \<^emph>\<open>not\<close> re-entrant:
  7.2187 -  direct or indirect nesting within the same thread will cause a deadlock!\<close>
  7.2188 +  direct or indirect nesting within the same thread will cause a deadlock!
  7.2189 +\<close>
  7.2190  
  7.2191  text %mlref \<open>
  7.2192    \begin{mldecls}
  7.2193 @@ -1777,31 +1749,29 @@
  7.2194    ('a -> ('b * 'a) option) -> 'b"} \\
  7.2195    \end{mldecls}
  7.2196  
  7.2197 -  \<^descr> Type @{ML_type "'a Synchronized.var"} represents synchronized
  7.2198 -  variables with state of type @{ML_type 'a}.
  7.2199 +    \<^descr> Type @{ML_type "'a Synchronized.var"} represents synchronized variables
  7.2200 +    with state of type @{ML_type 'a}.
  7.2201  
  7.2202 -  \<^descr> @{ML Synchronized.var}~\<open>name x\<close> creates a synchronized
  7.2203 -  variable that is initialized with value \<open>x\<close>.  The \<open>name\<close> is used for tracing.
  7.2204 +    \<^descr> @{ML Synchronized.var}~\<open>name x\<close> creates a synchronized variable that is
  7.2205 +    initialized with value \<open>x\<close>. The \<open>name\<close> is used for tracing.
  7.2206  
  7.2207 -  \<^descr> @{ML Synchronized.guarded_access}~\<open>var f\<close> lets the
  7.2208 -  function \<open>f\<close> operate within a critical section on the state
  7.2209 -  \<open>x\<close> as follows: if \<open>f x\<close> produces @{ML NONE}, it
  7.2210 -  continues to wait on the internal condition variable, expecting that
  7.2211 -  some other thread will eventually change the content in a suitable
  7.2212 -  manner; if \<open>f x\<close> produces @{ML SOME}~\<open>(y, x')\<close> it is
  7.2213 -  satisfied and assigns the new state value \<open>x'\<close>, broadcasts a
  7.2214 -  signal to all waiting threads on the associated condition variable,
  7.2215 -  and returns the result \<open>y\<close>.
  7.2216 +    \<^descr> @{ML Synchronized.guarded_access}~\<open>var f\<close> lets the function \<open>f\<close> operate
  7.2217 +    within a critical section on the state \<open>x\<close> as follows: if \<open>f x\<close> produces
  7.2218 +    @{ML NONE}, it continues to wait on the internal condition variable,
  7.2219 +    expecting that some other thread will eventually change the content in a
  7.2220 +    suitable manner; if \<open>f x\<close> produces @{ML SOME}~\<open>(y, x')\<close> it is satisfied and
  7.2221 +    assigns the new state value \<open>x'\<close>, broadcasts a signal to all waiting threads
  7.2222 +    on the associated condition variable, and returns the result \<open>y\<close>.
  7.2223  
  7.2224 -
  7.2225 -  There are some further variants of the @{ML
  7.2226 -  Synchronized.guarded_access} combinator, see @{file
  7.2227 -  "~~/src/Pure/Concurrent/synchronized.ML"} for details.
  7.2228 +  There are some further variants of the @{ML Synchronized.guarded_access}
  7.2229 +  combinator, see @{file "~~/src/Pure/Concurrent/synchronized.ML"} for
  7.2230 +  details.
  7.2231  \<close>
  7.2232  
  7.2233 -text %mlex \<open>The following example implements a counter that produces
  7.2234 -  positive integers that are unique over the runtime of the Isabelle
  7.2235 -  process:\<close>
  7.2236 +text %mlex \<open>
  7.2237 +  The following example implements a counter that produces positive integers
  7.2238 +  that are unique over the runtime of the Isabelle process:
  7.2239 +\<close>
  7.2240  
  7.2241  ML_val \<open>
  7.2242    local
  7.2243 @@ -1821,60 +1791,56 @@
  7.2244  
  7.2245  text \<open>
  7.2246    \<^medskip>
  7.2247 -  See @{file "~~/src/Pure/Concurrent/mailbox.ML"} how
  7.2248 -  to implement a mailbox as synchronized variable over a purely
  7.2249 -  functional list.\<close>
  7.2250 +  See @{file "~~/src/Pure/Concurrent/mailbox.ML"} how to implement a mailbox
  7.2251 +  as synchronized variable over a purely functional list.
  7.2252 +\<close>
  7.2253  
  7.2254  
  7.2255  section \<open>Managed evaluation\<close>
  7.2256  
  7.2257 -text \<open>Execution of Standard ML follows the model of strict
  7.2258 -  functional evaluation with optional exceptions.  Evaluation happens
  7.2259 -  whenever some function is applied to (sufficiently many)
  7.2260 -  arguments. The result is either an explicit value or an implicit
  7.2261 -  exception.
  7.2262 +text \<open>
  7.2263 +  Execution of Standard ML follows the model of strict functional evaluation
  7.2264 +  with optional exceptions. Evaluation happens whenever some function is
  7.2265 +  applied to (sufficiently many) arguments. The result is either an explicit
  7.2266 +  value or an implicit exception.
  7.2267  
  7.2268 -  \<^emph>\<open>Managed evaluation\<close> in Isabelle/ML organizes expressions and
  7.2269 -  results to control certain physical side-conditions, to say more
  7.2270 -  specifically when and how evaluation happens.  For example, the
  7.2271 -  Isabelle/ML library supports lazy evaluation with memoing, parallel
  7.2272 -  evaluation via futures, asynchronous evaluation via promises,
  7.2273 -  evaluation with time limit etc.
  7.2274 +  \<^emph>\<open>Managed evaluation\<close> in Isabelle/ML organizes expressions and results to
  7.2275 +  control certain physical side-conditions, to say more specifically when and
  7.2276 +  how evaluation happens. For example, the Isabelle/ML library supports lazy
  7.2277 +  evaluation with memoing, parallel evaluation via futures, asynchronous
  7.2278 +  evaluation via promises, evaluation with time limit etc.
  7.2279  
  7.2280    \<^medskip>
  7.2281 -  An \<^emph>\<open>unevaluated expression\<close> is represented either as
  7.2282 -  unit abstraction \<^verbatim>\<open>fn () => a\<close> of type
  7.2283 -  \<^verbatim>\<open>unit -> 'a\<close> or as regular function
  7.2284 -  \<^verbatim>\<open>fn a => b\<close> of type \<^verbatim>\<open>'a -> 'b\<close>.  Both forms
  7.2285 -  occur routinely, and special care is required to tell them apart ---
  7.2286 -  the static type-system of SML is only of limited help here.
  7.2287 +  An \<^emph>\<open>unevaluated expression\<close> is represented either as unit abstraction \<^verbatim>\<open>fn
  7.2288 +  () => a\<close> of type \<^verbatim>\<open>unit -> 'a\<close> or as regular function \<^verbatim>\<open>fn a => b\<close> of type
  7.2289 +  \<^verbatim>\<open>'a -> 'b\<close>. Both forms occur routinely, and special care is required to
  7.2290 +  tell them apart --- the static type-system of SML is only of limited help
  7.2291 +  here.
  7.2292  
  7.2293 -  The first form is more intuitive: some combinator \<open>(unit ->
  7.2294 -  'a) -> 'a\<close> applies the given function to \<open>()\<close> to initiate
  7.2295 -  the postponed evaluation process.  The second form is more flexible:
  7.2296 -  some combinator \<open>('a -> 'b) -> 'a -> 'b\<close> acts like a
  7.2297 -  modified form of function application; several such combinators may
  7.2298 -  be cascaded to modify a given function, before it is ultimately
  7.2299 -  applied to some argument.
  7.2300 +  The first form is more intuitive: some combinator \<open>(unit -> 'a) -> 'a\<close>
  7.2301 +  applies the given function to \<open>()\<close> to initiate the postponed evaluation
  7.2302 +  process. The second form is more flexible: some combinator \<open>('a -> 'b) -> 'a
  7.2303 +  -> 'b\<close> acts like a modified form of function application; several such
  7.2304 +  combinators may be cascaded to modify a given function, before it is
  7.2305 +  ultimately applied to some argument.
  7.2306  
  7.2307    \<^medskip>
  7.2308 -  \<^emph>\<open>Reified results\<close> make the disjoint sum of regular
  7.2309 -  values versions exceptional situations explicit as ML datatype:
  7.2310 -  \<open>'a result = Res of 'a | Exn of exn\<close>.  This is typically
  7.2311 -  used for administrative purposes, to store the overall outcome of an
  7.2312 -  evaluation process.
  7.2313 +  \<^emph>\<open>Reified results\<close> make the disjoint sum of regular values versions
  7.2314 +  exceptional situations explicit as ML datatype: \<open>'a result = Res of 'a | Exn
  7.2315 +  of exn\<close>. This is typically used for administrative purposes, to store the
  7.2316 +  overall outcome of an evaluation process.
  7.2317  
  7.2318 -  \<^emph>\<open>Parallel exceptions\<close> aggregate reified results, such that
  7.2319 -  multiple exceptions are digested as a collection in canonical form
  7.2320 -  that identifies exceptions according to their original occurrence.
  7.2321 -  This is particular important for parallel evaluation via futures
  7.2322 -  \secref{sec:futures}, which are organized as acyclic graph of
  7.2323 -  evaluations that depend on other evaluations: exceptions stemming
  7.2324 -  from shared sub-graphs are exposed exactly once and in the order of
  7.2325 -  their original occurrence (e.g.\ when printed at the toplevel).
  7.2326 -  Interrupt counts as neutral element here: it is treated as minimal
  7.2327 -  information about some canceled evaluation process, and is absorbed
  7.2328 -  by the presence of regular program exceptions.\<close>
  7.2329 +  \<^emph>\<open>Parallel exceptions\<close> aggregate reified results, such that multiple
  7.2330 +  exceptions are digested as a collection in canonical form that identifies
  7.2331 +  exceptions according to their original occurrence. This is particular
  7.2332 +  important for parallel evaluation via futures \secref{sec:futures}, which
  7.2333 +  are organized as acyclic graph of evaluations that depend on other
  7.2334 +  evaluations: exceptions stemming from shared sub-graphs are exposed exactly
  7.2335 +  once and in the order of their original occurrence (e.g.\ when printed at
  7.2336 +  the toplevel). Interrupt counts as neutral element here: it is treated as
  7.2337 +  minimal information about some canceled evaluation process, and is absorbed
  7.2338 +  by the presence of regular program exceptions.
  7.2339 +\<close>
  7.2340  
  7.2341  text %mlref \<open>
  7.2342    \begin{mldecls}
  7.2343 @@ -1886,54 +1852,49 @@
  7.2344    @{index_ML Par_Exn.release_first: "'a Exn.result list -> 'a list"} \\
  7.2345    \end{mldecls}
  7.2346  
  7.2347 -  \<^descr> Type @{ML_type "'a Exn.result"} represents the disjoint sum of
  7.2348 -  ML results explicitly, with constructor @{ML Exn.Res} for regular
  7.2349 -  values and @{ML "Exn.Exn"} for exceptions.
  7.2350 +  \<^descr> Type @{ML_type "'a Exn.result"} represents the disjoint sum of ML results
  7.2351 +  explicitly, with constructor @{ML Exn.Res} for regular values and @{ML
  7.2352 +  "Exn.Exn"} for exceptions.
  7.2353  
  7.2354 -  \<^descr> @{ML Exn.capture}~\<open>f x\<close> manages the evaluation of
  7.2355 -  \<open>f x\<close> such that exceptions are made explicit as @{ML
  7.2356 -  "Exn.Exn"}.  Note that this includes physical interrupts (see also
  7.2357 -  \secref{sec:exceptions}), so the same precautions apply to user
  7.2358 -  code: interrupts must not be absorbed accidentally!
  7.2359 +  \<^descr> @{ML Exn.capture}~\<open>f x\<close> manages the evaluation of \<open>f x\<close> such that
  7.2360 +  exceptions are made explicit as @{ML "Exn.Exn"}. Note that this includes
  7.2361 +  physical interrupts (see also \secref{sec:exceptions}), so the same
  7.2362 +  precautions apply to user code: interrupts must not be absorbed
  7.2363 +  accidentally!
  7.2364  
  7.2365 -  \<^descr> @{ML Exn.interruptible_capture} is similar to @{ML
  7.2366 -  Exn.capture}, but interrupts are immediately re-raised as required
  7.2367 -  for user code.
  7.2368 +  \<^descr> @{ML Exn.interruptible_capture} is similar to @{ML Exn.capture}, but
  7.2369 +  interrupts are immediately re-raised as required for user code.
  7.2370  
  7.2371 -  \<^descr> @{ML Exn.release}~\<open>result\<close> releases the original
  7.2372 -  runtime result, exposing its regular value or raising the reified
  7.2373 -  exception.
  7.2374 +  \<^descr> @{ML Exn.release}~\<open>result\<close> releases the original runtime result, exposing
  7.2375 +  its regular value or raising the reified exception.
  7.2376  
  7.2377 -  \<^descr> @{ML Par_Exn.release_all}~\<open>results\<close> combines results
  7.2378 -  that were produced independently (e.g.\ by parallel evaluation).  If
  7.2379 -  all results are regular values, that list is returned.  Otherwise,
  7.2380 -  the collection of all exceptions is raised, wrapped-up as collective
  7.2381 -  parallel exception.  Note that the latter prevents access to
  7.2382 -  individual exceptions by conventional \<^verbatim>\<open>handle\<close> of ML.
  7.2383 +  \<^descr> @{ML Par_Exn.release_all}~\<open>results\<close> combines results that were produced
  7.2384 +  independently (e.g.\ by parallel evaluation). If all results are regular
  7.2385 +  values, that list is returned. Otherwise, the collection of all exceptions
  7.2386 +  is raised, wrapped-up as collective parallel exception. Note that the latter
  7.2387 +  prevents access to individual exceptions by conventional \<^verbatim>\<open>handle\<close> of ML.
  7.2388  
  7.2389 -  \<^descr> @{ML Par_Exn.release_first} is similar to @{ML
  7.2390 -  Par_Exn.release_all}, but only the first (meaningful) exception that has
  7.2391 -  occurred in the original evaluation process is raised again, the others are
  7.2392 -  ignored.  That single exception may get handled by conventional
  7.2393 -  means in ML.
  7.2394 +  \<^descr> @{ML Par_Exn.release_first} is similar to @{ML Par_Exn.release_all}, but
  7.2395 +  only the first (meaningful) exception that has occurred in the original
  7.2396 +  evaluation process is raised again, the others are ignored. That single
  7.2397 +  exception may get handled by conventional means in ML.
  7.2398  \<close>
  7.2399  
  7.2400  
  7.2401  subsection \<open>Parallel skeletons \label{sec:parlist}\<close>
  7.2402  
  7.2403  text \<open>
  7.2404 -  Algorithmic skeletons are combinators that operate on lists in
  7.2405 -  parallel, in the manner of well-known \<open>map\<close>, \<open>exists\<close>,
  7.2406 -  \<open>forall\<close> etc.  Management of futures (\secref{sec:futures})
  7.2407 -  and their results as reified exceptions is wrapped up into simple
  7.2408 -  programming interfaces that resemble the sequential versions.
  7.2409 +  Algorithmic skeletons are combinators that operate on lists in parallel, in
  7.2410 +  the manner of well-known \<open>map\<close>, \<open>exists\<close>, \<open>forall\<close> etc. Management of
  7.2411 +  futures (\secref{sec:futures}) and their results as reified exceptions is
  7.2412 +  wrapped up into simple programming interfaces that resemble the sequential
  7.2413 +  versions.
  7.2414  
  7.2415 -  What remains is the application-specific problem to present
  7.2416 -  expressions with suitable \<^emph>\<open>granularity\<close>: each list element
  7.2417 -  corresponds to one evaluation task.  If the granularity is too
  7.2418 -  coarse, the available CPUs are not saturated.  If it is too
  7.2419 -  fine-grained, CPU cycles are wasted due to the overhead of
  7.2420 -  organizing parallel processing.  In the worst case, parallel
  7.2421 +  What remains is the application-specific problem to present expressions with
  7.2422 +  suitable \<^emph>\<open>granularity\<close>: each list element corresponds to one evaluation
  7.2423 +  task. If the granularity is too coarse, the available CPUs are not
  7.2424 +  saturated. If it is too fine-grained, CPU cycles are wasted due to the
  7.2425 +  overhead of organizing parallel processing. In the worst case, parallel
  7.2426    performance will be less than the sequential counterpart!
  7.2427  \<close>
  7.2428  
  7.2429 @@ -1943,31 +1904,29 @@
  7.2430    @{index_ML Par_List.get_some: "('a -> 'b option) -> 'a list -> 'b option"} \\
  7.2431    \end{mldecls}
  7.2432  
  7.2433 -  \<^descr> @{ML Par_List.map}~\<open>f [x\<^sub>1, \<dots>, x\<^sub>n]\<close> is like @{ML
  7.2434 -  "map"}~\<open>f [x\<^sub>1, \<dots>, x\<^sub>n]\<close>, but the evaluation of \<open>f x\<^sub>i\<close>
  7.2435 -  for \<open>i = 1, \<dots>, n\<close> is performed in parallel.
  7.2436 +  \<^descr> @{ML Par_List.map}~\<open>f [x\<^sub>1, \<dots>, x\<^sub>n]\<close> is like @{ML "map"}~\<open>f [x\<^sub>1, \<dots>,
  7.2437 +  x\<^sub>n]\<close>, but the evaluation of \<open>f x\<^sub>i\<close> for \<open>i = 1, \<dots>, n\<close> is performed in
  7.2438 +  parallel.
  7.2439  
  7.2440 -  An exception in any \<open>f x\<^sub>i\<close> cancels the overall evaluation
  7.2441 -  process.  The final result is produced via @{ML
  7.2442 -  Par_Exn.release_first} as explained above, which means the first
  7.2443 -  program exception that happened to occur in the parallel evaluation
  7.2444 -  is propagated, and all other failures are ignored.
  7.2445 +  An exception in any \<open>f x\<^sub>i\<close> cancels the overall evaluation process. The
  7.2446 +  final result is produced via @{ML Par_Exn.release_first} as explained above,
  7.2447 +  which means the first program exception that happened to occur in the
  7.2448 +  parallel evaluation is propagated, and all other failures are ignored.
  7.2449  
  7.2450 -  \<^descr> @{ML Par_List.get_some}~\<open>f [x\<^sub>1, \<dots>, x\<^sub>n]\<close> produces some
  7.2451 -  \<open>f x\<^sub>i\<close> that is of the form \<open>SOME y\<^sub>i\<close>, if that
  7.2452 -  exists, otherwise \<open>NONE\<close>.  Thus it is similar to @{ML
  7.2453 -  Library.get_first}, but subject to a non-deterministic parallel
  7.2454 -  choice process.  The first successful result cancels the overall
  7.2455 -  evaluation process; other exceptions are propagated as for @{ML
  7.2456 -  Par_List.map}.
  7.2457 +  \<^descr> @{ML Par_List.get_some}~\<open>f [x\<^sub>1, \<dots>, x\<^sub>n]\<close> produces some \<open>f x\<^sub>i\<close> that is of
  7.2458 +  the form \<open>SOME y\<^sub>i\<close>, if that exists, otherwise \<open>NONE\<close>. Thus it is similar to
  7.2459 +  @{ML Library.get_first}, but subject to a non-deterministic parallel choice
  7.2460 +  process. The first successful result cancels the overall evaluation process;
  7.2461 +  other exceptions are propagated as for @{ML Par_List.map}.
  7.2462  
  7.2463 -  This generic parallel choice combinator is the basis for derived
  7.2464 -  forms, such as @{ML Par_List.find_some}, @{ML Par_List.exists}, @{ML
  7.2465 -  Par_List.forall}.
  7.2466 +  This generic parallel choice combinator is the basis for derived forms, such
  7.2467 +  as @{ML Par_List.find_some}, @{ML Par_List.exists}, @{ML Par_List.forall}.
  7.2468  \<close>
  7.2469  
  7.2470 -text %mlex \<open>Subsequently, the Ackermann function is evaluated in
  7.2471 -  parallel for some ranges of arguments.\<close>
  7.2472 +text %mlex \<open>
  7.2473 +  Subsequently, the Ackermann function is evaluated in parallel for some
  7.2474 +  ranges of arguments.
  7.2475 +\<close>
  7.2476  
  7.2477  ML_val \<open>
  7.2478    fun ackermann 0 n = n + 1
  7.2479 @@ -1982,19 +1941,19 @@
  7.2480  subsection \<open>Lazy evaluation\<close>
  7.2481  
  7.2482  text \<open>
  7.2483 -  Classic lazy evaluation works via the \<open>lazy\<close>~/ \<open>force\<close> pair of
  7.2484 -  operations: \<open>lazy\<close> to wrap an unevaluated expression, and \<open>force\<close> to evaluate it once and store its result persistently. Later
  7.2485 -  invocations of \<open>force\<close> retrieve the stored result without another
  7.2486 -  evaluation. Isabelle/ML refines this idea to accommodate the aspects of
  7.2487 -  multi-threading, synchronous program exceptions and asynchronous interrupts.
  7.2488 +  Classic lazy evaluation works via the \<open>lazy\<close>~/ \<open>force\<close> pair of operations:
  7.2489 +  \<open>lazy\<close> to wrap an unevaluated expression, and \<open>force\<close> to evaluate it once
  7.2490 +  and store its result persistently. Later invocations of \<open>force\<close> retrieve the
  7.2491 +  stored result without another evaluation. Isabelle/ML refines this idea to
  7.2492 +  accommodate the aspects of multi-threading, synchronous program exceptions
  7.2493 +  and asynchronous interrupts.
  7.2494  
  7.2495 -  The first thread that invokes \<open>force\<close> on an unfinished lazy value
  7.2496 -  changes its state into a \<^emph>\<open>promise\<close> of the eventual result and starts
  7.2497 -  evaluating it. Any other threads that \<open>force\<close> the same lazy value in
  7.2498 -  the meantime need to wait for it to finish, by producing a regular result or
  7.2499 -  program exception. If the evaluation attempt is interrupted, this event is
  7.2500 -  propagated to all waiting threads and the lazy value is reset to its
  7.2501 -  original state.
  7.2502 +  The first thread that invokes \<open>force\<close> on an unfinished lazy value changes
  7.2503 +  its state into a \<^emph>\<open>promise\<close> of the eventual result and starts evaluating it.
  7.2504 +  Any other threads that \<open>force\<close> the same lazy value in the meantime need to
  7.2505 +  wait for it to finish, by producing a regular result or program exception.
  7.2506 +  If the evaluation attempt is interrupted, this event is propagated to all
  7.2507 +  waiting threads and the lazy value is reset to its original state.
  7.2508  
  7.2509    This means a lazy value is completely evaluated at most once, in a
  7.2510    thread-safe manner. There might be multiple interrupted evaluation attempts,
  7.2511 @@ -2013,11 +1972,11 @@
  7.2512  
  7.2513    \<^descr> Type @{ML_type "'a lazy"} represents lazy values over type \<^verbatim>\<open>'a\<close>.
  7.2514  
  7.2515 -  \<^descr> @{ML Lazy.lazy}~\<open>(fn () => e)\<close> wraps the unevaluated
  7.2516 -  expression \<open>e\<close> as unfinished lazy value.
  7.2517 +  \<^descr> @{ML Lazy.lazy}~\<open>(fn () => e)\<close> wraps the unevaluated expression \<open>e\<close> as
  7.2518 +  unfinished lazy value.
  7.2519  
  7.2520 -  \<^descr> @{ML Lazy.value}~\<open>a\<close> wraps the value \<open>a\<close> as finished lazy
  7.2521 -  value.  When forced, it returns \<open>a\<close> without any further evaluation.
  7.2522 +  \<^descr> @{ML Lazy.value}~\<open>a\<close> wraps the value \<open>a\<close> as finished lazy value. When
  7.2523 +  forced, it returns \<open>a\<close> without any further evaluation.
  7.2524  
  7.2525    There is very low overhead for this proforma wrapping of strict values as
  7.2526    lazy values.
  7.2527 @@ -2032,19 +1991,19 @@
  7.2528  
  7.2529  text \<open>
  7.2530    Futures help to organize parallel execution in a value-oriented manner, with
  7.2531 -  \<open>fork\<close>~/ \<open>join\<close> as the main pair of operations, and some further
  7.2532 -  variants; see also @{cite "Wenzel:2009" and "Wenzel:2013:ITP"}. Unlike lazy
  7.2533 -  values, futures are evaluated strictly and spontaneously on separate worker
  7.2534 -  threads. Futures may be canceled, which leads to interrupts on running
  7.2535 -  evaluation attempts, and forces structurally related futures to fail for all
  7.2536 -  time; already finished futures remain unchanged. Exceptions between related
  7.2537 +  \<open>fork\<close>~/ \<open>join\<close> as the main pair of operations, and some further variants;
  7.2538 +  see also @{cite "Wenzel:2009" and "Wenzel:2013:ITP"}. Unlike lazy values,
  7.2539 +  futures are evaluated strictly and spontaneously on separate worker threads.
  7.2540 +  Futures may be canceled, which leads to interrupts on running evaluation
  7.2541 +  attempts, and forces structurally related futures to fail for all time;
  7.2542 +  already finished futures remain unchanged. Exceptions between related
  7.2543    futures are propagated as well, and turned into parallel exceptions (see
  7.2544    above).
  7.2545  
  7.2546    Technically, a future is a single-assignment variable together with a
  7.2547 -  \<^emph>\<open>task\<close> that serves administrative purposes, notably within the
  7.2548 -  \<^emph>\<open>task queue\<close> where new futures are registered for eventual evaluation
  7.2549 -  and the worker threads retrieve their work.
  7.2550 +  \<^emph>\<open>task\<close> that serves administrative purposes, notably within the \<^emph>\<open>task
  7.2551 +  queue\<close> where new futures are registered for eventual evaluation and the
  7.2552 +  worker threads retrieve their work.
  7.2553  
  7.2554    The pool of worker threads is limited, in correlation with the number of
  7.2555    physical cores on the machine. Note that allocation of runtime resources may
  7.2556 @@ -2055,27 +2014,27 @@
  7.2557    timeout.
  7.2558  
  7.2559    \<^medskip>
  7.2560 -  Each future task belongs to some \<^emph>\<open>task group\<close>, which
  7.2561 -  represents the hierarchic structure of related tasks, together with the
  7.2562 -  exception status a that point. By default, the task group of a newly created
  7.2563 -  future is a new sub-group of the presently running one, but it is also
  7.2564 -  possible to indicate different group layouts under program control.
  7.2565 +  Each future task belongs to some \<^emph>\<open>task group\<close>, which represents the
  7.2566 +  hierarchic structure of related tasks, together with the exception status a
  7.2567 +  that point. By default, the task group of a newly created future is a new
  7.2568 +  sub-group of the presently running one, but it is also possible to indicate
  7.2569 +  different group layouts under program control.
  7.2570  
  7.2571    Cancellation of futures actually refers to the corresponding task group and
  7.2572    all its sub-groups. Thus interrupts are propagated down the group hierarchy.
  7.2573    Regular program exceptions are treated likewise: failure of the evaluation
  7.2574    of some future task affects its own group and all sub-groups. Given a
  7.2575 -  particular task group, its \<^emph>\<open>group status\<close> cumulates all relevant
  7.2576 -  exceptions according to its position within the group hierarchy. Interrupted
  7.2577 -  tasks that lack regular result information, will pick up parallel exceptions
  7.2578 -  from the cumulative group status.
  7.2579 +  particular task group, its \<^emph>\<open>group status\<close> cumulates all relevant exceptions
  7.2580 +  according to its position within the group hierarchy. Interrupted tasks that
  7.2581 +  lack regular result information, will pick up parallel exceptions from the
  7.2582 +  cumulative group status.
  7.2583  
  7.2584    \<^medskip>
  7.2585 -  A \<^emph>\<open>passive future\<close> or \<^emph>\<open>promise\<close> is a future with slightly
  7.2586 -  different evaluation policies: there is only a single-assignment variable
  7.2587 -  and some expression to evaluate for the \<^emph>\<open>failed\<close> case (e.g.\ to clean
  7.2588 -  up resources when canceled). A regular result is produced by external means,
  7.2589 -  using a separate \<^emph>\<open>fulfill\<close> operation.
  7.2590 +  A \<^emph>\<open>passive future\<close> or \<^emph>\<open>promise\<close> is a future with slightly different
  7.2591 +  evaluation policies: there is only a single-assignment variable and some
  7.2592 +  expression to evaluate for the \<^emph>\<open>failed\<close> case (e.g.\ to clean up resources
  7.2593 +  when canceled). A regular result is produced by external means, using a
  7.2594 +  separate \<^emph>\<open>fulfill\<close> operation.
  7.2595  
  7.2596    Promises are managed in the same task queue, so regular futures may depend
  7.2597    on them. This allows a form of reactive programming, where some promises are
  7.2598 @@ -2101,52 +2060,51 @@
  7.2599  
  7.2600    \<^descr> Type @{ML_type "'a future"} represents future values over type \<^verbatim>\<open>'a\<close>.
  7.2601  
  7.2602 -  \<^descr> @{ML Future.fork}~\<open>(fn () => e)\<close> registers the unevaluated
  7.2603 -  expression \<open>e\<close> as unfinished future value, to be evaluated eventually
  7.2604 -  on the parallel worker-thread farm. This is a shorthand for @{ML
  7.2605 -  Future.forks} below, with default parameters and a single expression.
  7.2606 +  \<^descr> @{ML Future.fork}~\<open>(fn () => e)\<close> registers the unevaluated expression \<open>e\<close>
  7.2607 +  as unfinished future value, to be evaluated eventually on the parallel
  7.2608 +  worker-thread farm. This is a shorthand for @{ML Future.forks} below, with
  7.2609 +  default parameters and a single expression.
  7.2610  
  7.2611 -  \<^descr> @{ML Future.forks}~\<open>params exprs\<close> is the general interface to
  7.2612 -  fork several futures simultaneously. The \<open>params\<close> consist of the
  7.2613 -  following fields:
  7.2614 +  \<^descr> @{ML Future.forks}~\<open>params exprs\<close> is the general interface to fork several
  7.2615 +  futures simultaneously. The \<open>params\<close> consist of the following fields:
  7.2616  
  7.2617 -    \<^item> \<open>name : string\<close> (default @{ML "\"\""}) specifies a common name
  7.2618 -    for the tasks of the forked futures, which serves diagnostic purposes.
  7.2619 +    \<^item> \<open>name : string\<close> (default @{ML "\"\""}) specifies a common name for the
  7.2620 +    tasks of the forked futures, which serves diagnostic purposes.
  7.2621  
  7.2622 -    \<^item> \<open>group : Future.group option\<close> (default @{ML NONE}) specifies
  7.2623 -    an optional task group for the forked futures. @{ML NONE} means that a new
  7.2624 -    sub-group of the current worker-thread task context is created. If this is
  7.2625 -    not a worker thread, the group will be a new root in the group hierarchy.
  7.2626 +    \<^item> \<open>group : Future.group option\<close> (default @{ML NONE}) specifies an optional
  7.2627 +    task group for the forked futures. @{ML NONE} means that a new sub-group
  7.2628 +    of the current worker-thread task context is created. If this is not a
  7.2629 +    worker thread, the group will be a new root in the group hierarchy.
  7.2630  
  7.2631 -    \<^item> \<open>deps : Future.task list\<close> (default @{ML "[]"}) specifies
  7.2632 -    dependencies on other future tasks, i.e.\ the adjacency relation in the
  7.2633 -    global task queue. Dependencies on already finished tasks are ignored.
  7.2634 +    \<^item> \<open>deps : Future.task list\<close> (default @{ML "[]"}) specifies dependencies on
  7.2635 +    other future tasks, i.e.\ the adjacency relation in the global task queue.
  7.2636 +    Dependencies on already finished tasks are ignored.
  7.2637  
  7.2638 -    \<^item> \<open>pri : int\<close> (default @{ML 0}) specifies a priority within the
  7.2639 -    task queue.
  7.2640 +    \<^item> \<open>pri : int\<close> (default @{ML 0}) specifies a priority within the task
  7.2641 +    queue.
  7.2642  
  7.2643 -    Typically there is only little deviation from the default priority @{ML 0}.
  7.2644 -    As a rule of thumb, @{ML "~1"} means ``low priority" and @{ML 1} means
  7.2645 +    Typically there is only little deviation from the default priority @{ML
  7.2646 +    0}. As a rule of thumb, @{ML "~1"} means ``low priority" and @{ML 1} means
  7.2647      ``high priority''.
  7.2648  
  7.2649 -    Note that the task priority only affects the position in the queue, not the
  7.2650 -    thread priority. When a worker thread picks up a task for processing, it
  7.2651 -    runs with the normal thread priority to the end (or until canceled). Higher
  7.2652 -    priority tasks that are queued later need to wait until this (or another)
  7.2653 -    worker thread becomes free again.
  7.2654 +    Note that the task priority only affects the position in the queue, not
  7.2655 +    the thread priority. When a worker thread picks up a task for processing,
  7.2656 +    it runs with the normal thread priority to the end (or until canceled).
  7.2657 +    Higher priority tasks that are queued later need to wait until this (or
  7.2658 +    another) worker thread becomes free again.
  7.2659  
  7.2660 -    \<^item> \<open>interrupts : bool\<close> (default @{ML true}) tells whether the
  7.2661 -    worker thread that processes the corresponding task is initially put into
  7.2662 -    interruptible state. This state may change again while running, by modifying
  7.2663 -    the thread attributes.
  7.2664 +    \<^item> \<open>interrupts : bool\<close> (default @{ML true}) tells whether the worker thread
  7.2665 +    that processes the corresponding task is initially put into interruptible
  7.2666 +    state. This state may change again while running, by modifying the thread
  7.2667 +    attributes.
  7.2668  
  7.2669 -    With interrupts disabled, a running future task cannot be canceled.  It is
  7.2670 +    With interrupts disabled, a running future task cannot be canceled. It is
  7.2671      the responsibility of the programmer that this special state is retained
  7.2672      only briefly.
  7.2673  
  7.2674 -  \<^descr> @{ML Future.join}~\<open>x\<close> retrieves the value of an already finished
  7.2675 -  future, which may lead to an exception, according to the result of its
  7.2676 -  previous evaluation.
  7.2677 +  \<^descr> @{ML Future.join}~\<open>x\<close> retrieves the value of an already finished future,
  7.2678 +  which may lead to an exception, according to the result of its previous
  7.2679 +  evaluation.
  7.2680  
  7.2681    For an unfinished future there are several cases depending on the role of
  7.2682    the current thread and the status of the future. A non-worker thread waits
  7.2683 @@ -2163,11 +2121,11 @@
  7.2684    some timeout.
  7.2685  
  7.2686    Whenever possible, static dependencies of futures should be specified
  7.2687 -  explicitly when forked (see \<open>deps\<close> above). Thus the evaluation can
  7.2688 -  work from the bottom up, without join conflicts and wait states.
  7.2689 +  explicitly when forked (see \<open>deps\<close> above). Thus the evaluation can work from
  7.2690 +  the bottom up, without join conflicts and wait states.
  7.2691  
  7.2692 -  \<^descr> @{ML Future.joins}~\<open>xs\<close> joins the given list of futures
  7.2693 -  simultaneously, which is more efficient than @{ML "map Future.join"}~\<open>xs\<close>.
  7.2694 +  \<^descr> @{ML Future.joins}~\<open>xs\<close> joins the given list of futures simultaneously,
  7.2695 +  which is more efficient than @{ML "map Future.join"}~\<open>xs\<close>.
  7.2696  
  7.2697    Based on the dependency graph of tasks, the current thread takes over the
  7.2698    responsibility to evaluate future expressions that are required for the main
  7.2699 @@ -2175,36 +2133,36 @@
  7.2700    presently evaluated on other threads only happens as last resort, when no
  7.2701    other unfinished futures are left over.
  7.2702  
  7.2703 -  \<^descr> @{ML Future.value}~\<open>a\<close> wraps the value \<open>a\<close> as finished
  7.2704 -  future value, bypassing the worker-thread farm. When joined, it returns
  7.2705 -  \<open>a\<close> without any further evaluation.
  7.2706 +  \<^descr> @{ML Future.value}~\<open>a\<close> wraps the value \<open>a\<close> as finished future value,
  7.2707 +  bypassing the worker-thread farm. When joined, it returns \<open>a\<close> without any
  7.2708 +  further evaluation.
  7.2709  
  7.2710    There is very low overhead for this proforma wrapping of strict values as
  7.2711    futures.
  7.2712  
  7.2713    \<^descr> @{ML Future.map}~\<open>f x\<close> is a fast-path implementation of @{ML
  7.2714 -  Future.fork}~\<open>(fn () => f (\<close>@{ML Future.join}~\<open>x))\<close>, which
  7.2715 -  avoids the full overhead of the task queue and worker-thread farm as far as
  7.2716 -  possible. The function \<open>f\<close> is supposed to be some trivial
  7.2717 -  post-processing or projection of the future result.
  7.2718 +  Future.fork}~\<open>(fn () => f (\<close>@{ML Future.join}~\<open>x))\<close>, which avoids the full
  7.2719 +  overhead of the task queue and worker-thread farm as far as possible. The
  7.2720 +  function \<open>f\<close> is supposed to be some trivial post-processing or projection of
  7.2721 +  the future result.
  7.2722  
  7.2723 -  \<^descr> @{ML Future.cancel}~\<open>x\<close> cancels the task group of the given
  7.2724 -  future, using @{ML Future.cancel_group} below.
  7.2725 +  \<^descr> @{ML Future.cancel}~\<open>x\<close> cancels the task group of the given future, using
  7.2726 +  @{ML Future.cancel_group} below.
  7.2727  
  7.2728 -  \<^descr> @{ML Future.cancel_group}~\<open>group\<close> cancels all tasks of the
  7.2729 -  given task group for all time. Threads that are presently processing a task
  7.2730 -  of the given group are interrupted: it may take some time until they are
  7.2731 -  actually terminated. Tasks that are queued but not yet processed are
  7.2732 -  dequeued and forced into interrupted state. Since the task group is itself
  7.2733 -  invalidated, any further attempt to fork a future that belongs to it will
  7.2734 -  yield a canceled result as well.
  7.2735 +  \<^descr> @{ML Future.cancel_group}~\<open>group\<close> cancels all tasks of the given task
  7.2736 +  group for all time. Threads that are presently processing a task of the
  7.2737 +  given group are interrupted: it may take some time until they are actually
  7.2738 +  terminated. Tasks that are queued but not yet processed are dequeued and
  7.2739 +  forced into interrupted state. Since the task group is itself invalidated,
  7.2740 +  any further attempt to fork a future that belongs to it will yield a
  7.2741 +  canceled result as well.
  7.2742  
  7.2743 -  \<^descr> @{ML Future.promise}~\<open>abort\<close> registers a passive future with the
  7.2744 -  given \<open>abort\<close> operation: it is invoked when the future task group is
  7.2745 -  canceled.
  7.2746 +  \<^descr> @{ML Future.promise}~\<open>abort\<close> registers a passive future with the given
  7.2747 +  \<open>abort\<close> operation: it is invoked when the future task group is canceled.
  7.2748  
  7.2749 -  \<^descr> @{ML Future.fulfill}~\<open>x a\<close> finishes the passive future \<open>x\<close> by the given value \<open>a\<close>. If the promise has already been canceled,
  7.2750 -  the attempt to fulfill it causes an exception.
  7.2751 +  \<^descr> @{ML Future.fulfill}~\<open>x a\<close> finishes the passive future \<open>x\<close> by the given
  7.2752 +  value \<open>a\<close>. If the promise has already been canceled, the attempt to fulfill
  7.2753 +  it causes an exception.
  7.2754  \<close>
  7.2755  
  7.2756  end
     8.1 --- a/src/Doc/Implementation/Prelim.thy	Tue Dec 15 14:41:47 2015 +0000
     8.2 +++ b/src/Doc/Implementation/Prelim.thy	Wed Dec 16 17:30:30 2015 +0100
     8.3 @@ -9,88 +9,78 @@
     8.4  section \<open>Contexts \label{sec:context}\<close>
     8.5  
     8.6  text \<open>
     8.7 -  A logical context represents the background that is required for
     8.8 -  formulating statements and composing proofs.  It acts as a medium to
     8.9 -  produce formal content, depending on earlier material (declarations,
    8.10 -  results etc.).
    8.11 +  A logical context represents the background that is required for formulating
    8.12 +  statements and composing proofs. It acts as a medium to produce formal
    8.13 +  content, depending on earlier material (declarations, results etc.).
    8.14  
    8.15 -  For example, derivations within the Isabelle/Pure logic can be
    8.16 -  described as a judgment \<open>\<Gamma> \<turnstile>\<^sub>\<Theta> \<phi>\<close>, which means that a
    8.17 -  proposition \<open>\<phi>\<close> is derivable from hypotheses \<open>\<Gamma>\<close>
    8.18 -  within the theory \<open>\<Theta>\<close>.  There are logical reasons for
    8.19 -  keeping \<open>\<Theta>\<close> and \<open>\<Gamma>\<close> separate: theories can be
    8.20 -  liberal about supporting type constructors and schematic
    8.21 -  polymorphism of constants and axioms, while the inner calculus of
    8.22 -  \<open>\<Gamma> \<turnstile> \<phi>\<close> is strictly limited to Simple Type Theory (with
    8.23 +  For example, derivations within the Isabelle/Pure logic can be described as
    8.24 +  a judgment \<open>\<Gamma> \<turnstile>\<^sub>\<Theta> \<phi>\<close>, which means that a proposition \<open>\<phi>\<close> is derivable from
    8.25 +  hypotheses \<open>\<Gamma>\<close> within the theory \<open>\<Theta>\<close>. There are logical reasons for keeping
    8.26 +  \<open>\<Theta>\<close> and \<open>\<Gamma>\<close> separate: theories can be liberal about supporting type
    8.27 +  constructors and schematic polymorphism of constants and axioms, while the
    8.28 +  inner calculus of \<open>\<Gamma> \<turnstile> \<phi>\<close> is strictly limited to Simple Type Theory (with
    8.29    fixed type variables in the assumptions).
    8.30  
    8.31    \<^medskip>
    8.32 -  Contexts and derivations are linked by the following key
    8.33 -  principles:
    8.34 +  Contexts and derivations are linked by the following key principles:
    8.35  
    8.36 -  \<^item> Transfer: monotonicity of derivations admits results to be
    8.37 -  transferred into a \<^emph>\<open>larger\<close> context, i.e.\ \<open>\<Gamma> \<turnstile>\<^sub>\<Theta>
    8.38 -  \<phi>\<close> implies \<open>\<Gamma>' \<turnstile>\<^sub>\<Theta>\<^sub>' \<phi>\<close> for contexts \<open>\<Theta>'
    8.39 -  \<supseteq> \<Theta>\<close> and \<open>\<Gamma>' \<supseteq> \<Gamma>\<close>.
    8.40 +  \<^item> Transfer: monotonicity of derivations admits results to be transferred
    8.41 +  into a \<^emph>\<open>larger\<close> context, i.e.\ \<open>\<Gamma> \<turnstile>\<^sub>\<Theta> \<phi>\<close> implies \<open>\<Gamma>' \<turnstile>\<^sub>\<Theta>\<^sub>' \<phi>\<close> for contexts
    8.42 +  \<open>\<Theta>' \<supseteq> \<Theta>\<close> and \<open>\<Gamma>' \<supseteq> \<Gamma>\<close>.
    8.43  
    8.44 -  \<^item> Export: discharge of hypotheses admits results to be exported
    8.45 -  into a \<^emph>\<open>smaller\<close> context, i.e.\ \<open>\<Gamma>' \<turnstile>\<^sub>\<Theta> \<phi>\<close>
    8.46 -  implies \<open>\<Gamma> \<turnstile>\<^sub>\<Theta> \<Delta> \<Longrightarrow> \<phi>\<close> where \<open>\<Gamma>' \<supseteq> \<Gamma>\<close> and
    8.47 -  \<open>\<Delta> = \<Gamma>' - \<Gamma>\<close>.  Note that \<open>\<Theta>\<close> remains unchanged here,
    8.48 -  only the \<open>\<Gamma>\<close> part is affected.
    8.49 +  \<^item> Export: discharge of hypotheses admits results to be exported into a
    8.50 +  \<^emph>\<open>smaller\<close> context, i.e.\ \<open>\<Gamma>' \<turnstile>\<^sub>\<Theta> \<phi>\<close> implies \<open>\<Gamma> \<turnstile>\<^sub>\<Theta> \<Delta> \<Longrightarrow> \<phi>\<close> where \<open>\<Gamma>' \<supseteq> \<Gamma>\<close>
    8.51 +  and \<open>\<Delta> = \<Gamma>' - \<Gamma>\<close>. Note that \<open>\<Theta>\<close> remains unchanged here, only the \<open>\<Gamma>\<close> part is
    8.52 +  affected.
    8.53  
    8.54  
    8.55    \<^medskip>
    8.56 -  By modeling the main characteristics of the primitive
    8.57 -  \<open>\<Theta>\<close> and \<open>\<Gamma>\<close> above, and abstracting over any
    8.58 -  particular logical content, we arrive at the fundamental notions of
    8.59 -  \<^emph>\<open>theory context\<close> and \<^emph>\<open>proof context\<close> in Isabelle/Isar.
    8.60 -  These implement a certain policy to manage arbitrary \<^emph>\<open>context
    8.61 -  data\<close>.  There is a strongly-typed mechanism to declare new kinds of
    8.62 +  By modeling the main characteristics of the primitive \<open>\<Theta>\<close> and \<open>\<Gamma>\<close> above, and
    8.63 +  abstracting over any particular logical content, we arrive at the
    8.64 +  fundamental notions of \<^emph>\<open>theory context\<close> and \<^emph>\<open>proof context\<close> in
    8.65 +  Isabelle/Isar. These implement a certain policy to manage arbitrary
    8.66 +  \<^emph>\<open>context data\<close>. There is a strongly-typed mechanism to declare new kinds of
    8.67    data at compile time.
    8.68  
    8.69 -  The internal bootstrap process of Isabelle/Pure eventually reaches a
    8.70 -  stage where certain data slots provide the logical content of \<open>\<Theta>\<close> and \<open>\<Gamma>\<close> sketched above, but this does not stop there!
    8.71 -  Various additional data slots support all kinds of mechanisms that
    8.72 -  are not necessarily part of the core logic.
    8.73 +  The internal bootstrap process of Isabelle/Pure eventually reaches a stage
    8.74 +  where certain data slots provide the logical content of \<open>\<Theta>\<close> and \<open>\<Gamma>\<close> sketched
    8.75 +  above, but this does not stop there! Various additional data slots support
    8.76 +  all kinds of mechanisms that are not necessarily part of the core logic.
    8.77  
    8.78 -  For example, there would be data for canonical introduction and
    8.79 -  elimination rules for arbitrary operators (depending on the
    8.80 -  object-logic and application), which enables users to perform
    8.81 -  standard proof steps implicitly (cf.\ the \<open>rule\<close> method
    8.82 -  @{cite "isabelle-isar-ref"}).
    8.83 +  For example, there would be data for canonical introduction and elimination
    8.84 +  rules for arbitrary operators (depending on the object-logic and
    8.85 +  application), which enables users to perform standard proof steps implicitly
    8.86 +  (cf.\ the \<open>rule\<close> method @{cite "isabelle-isar-ref"}).
    8.87  
    8.88    \<^medskip>
    8.89 -  Thus Isabelle/Isar is able to bring forth more and more
    8.90 -  concepts successively.  In particular, an object-logic like
    8.91 -  Isabelle/HOL continues the Isabelle/Pure setup by adding specific
    8.92 -  components for automated reasoning (classical reasoner, tableau
    8.93 -  prover, structured induction etc.) and derived specification
    8.94 -  mechanisms (inductive predicates, recursive functions etc.).  All of
    8.95 -  this is ultimately based on the generic data management by theory
    8.96 -  and proof contexts introduced here.
    8.97 +  Thus Isabelle/Isar is able to bring forth more and more concepts
    8.98 +  successively. In particular, an object-logic like Isabelle/HOL continues the
    8.99 +  Isabelle/Pure setup by adding specific components for automated reasoning
   8.100 +  (classical reasoner, tableau prover, structured induction etc.) and derived
   8.101 +  specification mechanisms (inductive predicates, recursive functions etc.).
   8.102 +  All of this is ultimately based on the generic data management by theory and
   8.103 +  proof contexts introduced here.
   8.104  \<close>
   8.105  
   8.106  
   8.107  subsection \<open>Theory context \label{sec:context-theory}\<close>
   8.108  
   8.109 -text \<open>A \<^emph>\<open>theory\<close> is a data container with explicit name and
   8.110 -  unique identifier.  Theories are related by a (nominal) sub-theory
   8.111 -  relation, which corresponds to the dependency graph of the original
   8.112 -  construction; each theory is derived from a certain sub-graph of
   8.113 -  ancestor theories.  To this end, the system maintains a set of
   8.114 -  symbolic ``identification stamps'' within each theory.
   8.115 +text \<open>
   8.116 +  A \<^emph>\<open>theory\<close> is a data container with explicit name and unique identifier.
   8.117 +  Theories are related by a (nominal) sub-theory relation, which corresponds
   8.118 +  to the dependency graph of the original construction; each theory is derived
   8.119 +  from a certain sub-graph of ancestor theories. To this end, the system
   8.120 +  maintains a set of symbolic ``identification stamps'' within each theory.
   8.121  
   8.122 -  The \<open>begin\<close> operation starts a new theory by importing several
   8.123 -  parent theories (with merged contents) and entering a special mode of
   8.124 -  nameless incremental updates, until the final \<open>end\<close> operation is
   8.125 -  performed.
   8.126 +  The \<open>begin\<close> operation starts a new theory by importing several parent
   8.127 +  theories (with merged contents) and entering a special mode of nameless
   8.128 +  incremental updates, until the final \<open>end\<close> operation is performed.
   8.129  
   8.130    \<^medskip>
   8.131 -  The example in \figref{fig:ex-theory} below shows a theory
   8.132 -  graph derived from \<open>Pure\<close>, with theory \<open>Length\<close>
   8.133 -  importing \<open>Nat\<close> and \<open>List\<close>.  The body of \<open>Length\<close> consists of a sequence of updates, resulting in locally a
   8.134 -  linear sub-theory relation for each intermediate step.
   8.135 +  The example in \figref{fig:ex-theory} below shows a theory graph derived
   8.136 +  from \<open>Pure\<close>, with theory \<open>Length\<close> importing \<open>Nat\<close> and \<open>List\<close>. The body of
   8.137 +  \<open>Length\<close> consists of a sequence of updates, resulting in locally a linear
   8.138 +  sub-theory relation for each intermediate step.
   8.139  
   8.140    \begin{figure}[htb]
   8.141    \begin{center}
   8.142 @@ -111,10 +101,10 @@
   8.143    \end{figure}
   8.144  
   8.145    \<^medskip>
   8.146 -  Derived formal entities may retain a reference to the
   8.147 -  background theory in order to indicate the formal context from which
   8.148 -  they were produced.  This provides an immutable certificate of the
   8.149 -  background theory.\<close>
   8.150 +  Derived formal entities may retain a reference to the background theory in
   8.151 +  order to indicate the formal context from which they were produced. This
   8.152 +  provides an immutable certificate of the background theory.
   8.153 +\<close>
   8.154  
   8.155  text %mlref \<open>
   8.156    \begin{mldecls}
   8.157 @@ -128,24 +118,21 @@
   8.158  
   8.159    \<^descr> Type @{ML_type theory} represents theory contexts.
   8.160  
   8.161 -  \<^descr> @{ML "Context.eq_thy"}~\<open>(thy\<^sub>1, thy\<^sub>2)\<close> check strict
   8.162 -  identity of two theories.
   8.163 +  \<^descr> @{ML "Context.eq_thy"}~\<open>(thy\<^sub>1, thy\<^sub>2)\<close> check strict identity of two
   8.164 +  theories.
   8.165  
   8.166 -  \<^descr> @{ML "Context.subthy"}~\<open>(thy\<^sub>1, thy\<^sub>2)\<close> compares theories
   8.167 -  according to the intrinsic graph structure of the construction.
   8.168 -  This sub-theory relation is a nominal approximation of inclusion
   8.169 -  (\<open>\<subseteq>\<close>) of the corresponding content (according to the
   8.170 -  semantics of the ML modules that implement the data).
   8.171 +  \<^descr> @{ML "Context.subthy"}~\<open>(thy\<^sub>1, thy\<^sub>2)\<close> compares theories according to the
   8.172 +  intrinsic graph structure of the construction. This sub-theory relation is a
   8.173 +  nominal approximation of inclusion (\<open>\<subseteq>\<close>) of the corresponding content
   8.174 +  (according to the semantics of the ML modules that implement the data).
   8.175  
   8.176 -  \<^descr> @{ML "Theory.begin_theory"}~\<open>name parents\<close> constructs
   8.177 -  a new theory based on the given parents.  This ML function is
   8.178 -  normally not invoked directly.
   8.179 +  \<^descr> @{ML "Theory.begin_theory"}~\<open>name parents\<close> constructs a new theory based
   8.180 +  on the given parents. This ML function is normally not invoked directly.
   8.181  
   8.182 -  \<^descr> @{ML "Theory.parents_of"}~\<open>thy\<close> returns the direct
   8.183 -  ancestors of \<open>thy\<close>.
   8.184 +  \<^descr> @{ML "Theory.parents_of"}~\<open>thy\<close> returns the direct ancestors of \<open>thy\<close>.
   8.185  
   8.186 -  \<^descr> @{ML "Theory.ancestors_of"}~\<open>thy\<close> returns all
   8.187 -  ancestors of \<open>thy\<close> (not including \<open>thy\<close> itself).
   8.188 +  \<^descr> @{ML "Theory.ancestors_of"}~\<open>thy\<close> returns all ancestors of \<open>thy\<close> (not
   8.189 +  including \<open>thy\<close> itself).
   8.190  \<close>
   8.191  
   8.192  text %mlantiq \<open>
   8.193 @@ -160,45 +147,43 @@
   8.194    @@{ML_antiquotation theory_context} nameref
   8.195    \<close>}
   8.196  
   8.197 -  \<^descr> \<open>@{theory}\<close> refers to the background theory of the
   8.198 -  current context --- as abstract value.
   8.199 +  \<^descr> \<open>@{theory}\<close> refers to the background theory of the current context --- as
   8.200 +  abstract value.
   8.201  
   8.202 -  \<^descr> \<open>@{theory A}\<close> refers to an explicitly named ancestor
   8.203 -  theory \<open>A\<close> of the background theory of the current context
   8.204 -  --- as abstract value.
   8.205 +  \<^descr> \<open>@{theory A}\<close> refers to an explicitly named ancestor theory \<open>A\<close> of the
   8.206 +  background theory of the current context --- as abstract value.
   8.207  
   8.208 -  \<^descr> \<open>@{theory_context A}\<close> is similar to \<open>@{theory
   8.209 -  A}\<close>, but presents the result as initial @{ML_type Proof.context}
   8.210 -  (see also @{ML Proof_Context.init_global}).
   8.211 +  \<^descr> \<open>@{theory_context A}\<close> is similar to \<open>@{theory A}\<close>, but presents the result
   8.212 +  as initial @{ML_type Proof.context} (see also @{ML
   8.213 +  Proof_Context.init_global}).
   8.214  \<close>
   8.215  
   8.216  
   8.217  subsection \<open>Proof context \label{sec:context-proof}\<close>
   8.218  
   8.219 -text \<open>A proof context is a container for pure data that refers to
   8.220 -  the theory from which it is derived. The \<open>init\<close> operation
   8.221 -  creates a proof context from a given theory. There is an explicit
   8.222 -  \<open>transfer\<close> operation to force resynchronization with updates
   8.223 -  to the background theory -- this is rarely required in practice.
   8.224 +text \<open>
   8.225 +  A proof context is a container for pure data that refers to the theory from
   8.226 +  which it is derived. The \<open>init\<close> operation creates a proof context from a
   8.227 +  given theory. There is an explicit \<open>transfer\<close> operation to force
   8.228 +  resynchronization with updates to the background theory -- this is rarely
   8.229 +  required in practice.
   8.230  
   8.231 -  Entities derived in a proof context need to record logical
   8.232 -  requirements explicitly, since there is no separate context
   8.233 -  identification or symbolic inclusion as for theories.  For example,
   8.234 -  hypotheses used in primitive derivations (cf.\ \secref{sec:thms})
   8.235 -  are recorded separately within the sequent \<open>\<Gamma> \<turnstile> \<phi>\<close>, just to
   8.236 -  make double sure.  Results could still leak into an alien proof
   8.237 -  context due to programming errors, but Isabelle/Isar includes some
   8.238 -  extra validity checks in critical positions, notably at the end of a
   8.239 +  Entities derived in a proof context need to record logical requirements
   8.240 +  explicitly, since there is no separate context identification or symbolic
   8.241 +  inclusion as for theories. For example, hypotheses used in primitive
   8.242 +  derivations (cf.\ \secref{sec:thms}) are recorded separately within the
   8.243 +  sequent \<open>\<Gamma> \<turnstile> \<phi>\<close>, just to make double sure. Results could still leak into an
   8.244 +  alien proof context due to programming errors, but Isabelle/Isar includes
   8.245 +  some extra validity checks in critical positions, notably at the end of a
   8.246    sub-proof.
   8.247  
   8.248    Proof contexts may be manipulated arbitrarily, although the common
   8.249 -  discipline is to follow block structure as a mental model: a given
   8.250 -  context is extended consecutively, and results are exported back
   8.251 -  into the original context.  Note that an Isar proof state models
   8.252 -  block-structured reasoning explicitly, using a stack of proof
   8.253 -  contexts internally.  For various technical reasons, the background
   8.254 -  theory of an Isar proof state must not be changed while the proof is
   8.255 -  still under construction!
   8.256 +  discipline is to follow block structure as a mental model: a given context
   8.257 +  is extended consecutively, and results are exported back into the original
   8.258 +  context. Note that an Isar proof state models block-structured reasoning
   8.259 +  explicitly, using a stack of proof contexts internally. For various
   8.260 +  technical reasons, the background theory of an Isar proof state must not be
   8.261 +  changed while the proof is still under construction!
   8.262  \<close>
   8.263  
   8.264  text %mlref \<open>
   8.265 @@ -211,14 +196,14 @@
   8.266  
   8.267    \<^descr> Type @{ML_type Proof.context} represents proof contexts.
   8.268  
   8.269 -  \<^descr> @{ML Proof_Context.init_global}~\<open>thy\<close> produces a proof
   8.270 -  context derived from \<open>thy\<close>, initializing all data.
   8.271 +  \<^descr> @{ML Proof_Context.init_global}~\<open>thy\<close> produces a proof context derived
   8.272 +  from \<open>thy\<close>, initializing all data.
   8.273  
   8.274 -  \<^descr> @{ML Proof_Context.theory_of}~\<open>ctxt\<close> selects the
   8.275 -  background theory from \<open>ctxt\<close>.
   8.276 +  \<^descr> @{ML Proof_Context.theory_of}~\<open>ctxt\<close> selects the background theory from
   8.277 +  \<open>ctxt\<close>.
   8.278  
   8.279 -  \<^descr> @{ML Proof_Context.transfer}~\<open>thy ctxt\<close> promotes the
   8.280 -  background theory of \<open>ctxt\<close> to the super theory \<open>thy\<close>.
   8.281 +  \<^descr> @{ML Proof_Context.transfer}~\<open>thy ctxt\<close> promotes the background theory of
   8.282 +  \<open>ctxt\<close> to the super theory \<open>thy\<close>.
   8.283  \<close>
   8.284  
   8.285  text %mlantiq \<open>
   8.286 @@ -226,9 +211,9 @@
   8.287    @{ML_antiquotation_def "context"} & : & \<open>ML_antiquotation\<close> \\
   8.288    \end{matharray}
   8.289  
   8.290 -  \<^descr> \<open>@{context}\<close> refers to \<^emph>\<open>the\<close> context at
   8.291 -  compile-time --- as abstract value.  Independently of (local) theory
   8.292 -  or proof mode, this always produces a meaningful result.
   8.293 +  \<^descr> \<open>@{context}\<close> refers to \<^emph>\<open>the\<close> context at compile-time --- as abstract
   8.294 +  value. Independently of (local) theory or proof mode, this always produces a
   8.295 +  meaningful result.
   8.296  
   8.297    This is probably the most common antiquotation in interactive
   8.298    experimentation with ML inside Isar.
   8.299 @@ -238,17 +223,16 @@
   8.300  subsection \<open>Generic contexts \label{sec:generic-context}\<close>
   8.301  
   8.302  text \<open>
   8.303 -  A generic context is the disjoint sum of either a theory or proof
   8.304 -  context.  Occasionally, this enables uniform treatment of generic
   8.305 -  context data, typically extra-logical information.  Operations on
   8.306 -  generic contexts include the usual injections, partial selections,
   8.307 -  and combinators for lifting operations on either component of the
   8.308 -  disjoint sum.
   8.309 +  A generic context is the disjoint sum of either a theory or proof context.
   8.310 +  Occasionally, this enables uniform treatment of generic context data,
   8.311 +  typically extra-logical information. Operations on generic contexts include
   8.312 +  the usual injections, partial selections, and combinators for lifting
   8.313 +  operations on either component of the disjoint sum.
   8.314  
   8.315 -  Moreover, there are total operations \<open>theory_of\<close> and \<open>proof_of\<close> to convert a generic context into either kind: a theory
   8.316 -  can always be selected from the sum, while a proof context might
   8.317 -  have to be constructed by an ad-hoc \<open>init\<close> operation, which
   8.318 -  incurs a small runtime overhead.
   8.319 +  Moreover, there are total operations \<open>theory_of\<close> and \<open>proof_of\<close> to convert a
   8.320 +  generic context into either kind: a theory can always be selected from the
   8.321 +  sum, while a proof context might have to be constructed by an ad-hoc \<open>init\<close>
   8.322 +  operation, which incurs a small runtime overhead.
   8.323  \<close>
   8.324  
   8.325  text %mlref \<open>
   8.326 @@ -258,27 +242,27 @@
   8.327    @{index_ML Context.proof_of: "Context.generic -> Proof.context"} \\
   8.328    \end{mldecls}
   8.329  
   8.330 -  \<^descr> Type @{ML_type Context.generic} is the direct sum of @{ML_type
   8.331 -  "theory"} and @{ML_type "Proof.context"}, with the datatype
   8.332 -  constructors @{ML "Context.Theory"} and @{ML "Context.Proof"}.
   8.333 +  \<^descr> Type @{ML_type Context.generic} is the direct sum of @{ML_type "theory"}
   8.334 +  and @{ML_type "Proof.context"}, with the datatype constructors @{ML
   8.335 +  "Context.Theory"} and @{ML "Context.Proof"}.
   8.336  
   8.337 -  \<^descr> @{ML Context.theory_of}~\<open>context\<close> always produces a
   8.338 -  theory from the generic \<open>context\<close>, using @{ML
   8.339 -  "Proof_Context.theory_of"} as required.
   8.340 +  \<^descr> @{ML Context.theory_of}~\<open>context\<close> always produces a theory from the
   8.341 +  generic \<open>context\<close>, using @{ML "Proof_Context.theory_of"} as required.
   8.342  
   8.343 -  \<^descr> @{ML Context.proof_of}~\<open>context\<close> always produces a
   8.344 -  proof context from the generic \<open>context\<close>, using @{ML
   8.345 -  "Proof_Context.init_global"} as required (note that this re-initializes the
   8.346 -  context data with each invocation).
   8.347 +  \<^descr> @{ML Context.proof_of}~\<open>context\<close> always produces a proof context from the
   8.348 +  generic \<open>context\<close>, using @{ML "Proof_Context.init_global"} as required (note
   8.349 +  that this re-initializes the context data with each invocation).
   8.350  \<close>
   8.351  
   8.352  
   8.353  subsection \<open>Context data \label{sec:context-data}\<close>
   8.354  
   8.355 -text \<open>The main purpose of theory and proof contexts is to manage
   8.356 -  arbitrary (pure) data.  New data types can be declared incrementally
   8.357 -  at compile time.  There are separate declaration mechanisms for any
   8.358 -  of the three kinds of contexts: theory, proof, generic.\<close>
   8.359 +text \<open>
   8.360 +  The main purpose of theory and proof contexts is to manage arbitrary (pure)
   8.361 +  data. New data types can be declared incrementally at compile time. There
   8.362 +  are separate declaration mechanisms for any of the three kinds of contexts:
   8.363 +  theory, proof, generic.
   8.364 +\<close>
   8.365  
   8.366  paragraph \<open>Theory data\<close>
   8.367  text \<open>declarations need to implement the following ML signature:
   8.368 @@ -292,18 +276,18 @@
   8.369    \end{tabular}
   8.370    \<^medskip>
   8.371  
   8.372 -  The \<open>empty\<close> value acts as initial default for \<^emph>\<open>any\<close>
   8.373 -  theory that does not declare actual data content; \<open>extend\<close>
   8.374 -  is acts like a unitary version of \<open>merge\<close>.
   8.375 +  The \<open>empty\<close> value acts as initial default for \<^emph>\<open>any\<close> theory that does not
   8.376 +  declare actual data content; \<open>extend\<close> is acts like a unitary version of
   8.377 +  \<open>merge\<close>.
   8.378  
   8.379 -  Implementing \<open>merge\<close> can be tricky.  The general idea is
   8.380 -  that \<open>merge (data\<^sub>1, data\<^sub>2)\<close> inserts those parts of \<open>data\<^sub>2\<close> into \<open>data\<^sub>1\<close> that are not yet present, while
   8.381 -  keeping the general order of things.  The @{ML Library.merge}
   8.382 +  Implementing \<open>merge\<close> can be tricky. The general idea is that \<open>merge (data\<^sub>1,
   8.383 +  data\<^sub>2)\<close> inserts those parts of \<open>data\<^sub>2\<close> into \<open>data\<^sub>1\<close> that are not yet
   8.384 +  present, while keeping the general order of things. The @{ML Library.merge}
   8.385    function on plain lists may serve as canonical template.
   8.386  
   8.387 -  Particularly note that shared parts of the data must not be
   8.388 -  duplicated by naive concatenation, or a theory graph that is like a
   8.389 -  chain of diamonds would cause an exponential blowup!
   8.390 +  Particularly note that shared parts of the data must not be duplicated by
   8.391 +  naive concatenation, or a theory graph that is like a chain of diamonds
   8.392 +  would cause an exponential blowup!
   8.393  \<close>
   8.394  
   8.395  paragraph \<open>Proof context data\<close>
   8.396 @@ -316,26 +300,25 @@
   8.397    \end{tabular}
   8.398    \<^medskip>
   8.399  
   8.400 -  The \<open>init\<close> operation is supposed to produce a pure value
   8.401 -  from the given background theory and should be somehow
   8.402 -  ``immediate''.  Whenever a proof context is initialized, which
   8.403 -  happens frequently, the the system invokes the \<open>init\<close>
   8.404 -  operation of \<^emph>\<open>all\<close> theory data slots ever declared.  This also
   8.405 -  means that one needs to be economic about the total number of proof
   8.406 -  data declarations in the system, i.e.\ each ML module should declare
   8.407 -  at most one, sometimes two data slots for its internal use.
   8.408 -  Repeated data declarations to simulate a record type should be
   8.409 -  avoided!
   8.410 +  The \<open>init\<close> operation is supposed to produce a pure value from the given
   8.411 +  background theory and should be somehow ``immediate''. Whenever a proof
   8.412 +  context is initialized, which happens frequently, the the system invokes the
   8.413 +  \<open>init\<close> operation of \<^emph>\<open>all\<close> theory data slots ever declared. This also means
   8.414 +  that one needs to be economic about the total number of proof data
   8.415 +  declarations in the system, i.e.\ each ML module should declare at most one,
   8.416 +  sometimes two data slots for its internal use. Repeated data declarations to
   8.417 +  simulate a record type should be avoided!
   8.418  \<close>
   8.419  
   8.420  paragraph \<open>Generic data\<close>
   8.421 -text \<open>provides a hybrid interface for both theory and proof data. The \<open>init\<close>
   8.422 -  operation for proof contexts is predefined to select the current data
   8.423 -  value from the background theory.
   8.424 +text \<open>
   8.425 +  provides a hybrid interface for both theory and proof data. The \<open>init\<close>
   8.426 +  operation for proof contexts is predefined to select the current data value
   8.427 +  from the background theory.
   8.428  
   8.429    \<^bigskip>
   8.430 -  Any of the above data declarations over type \<open>T\<close>
   8.431 -  result in an ML structure with the following signature:
   8.432 +  Any of the above data declarations over type \<open>T\<close> result in an ML structure
   8.433 +  with the following signature:
   8.434  
   8.435    \<^medskip>
   8.436    \begin{tabular}{ll}
   8.437 @@ -345,12 +328,12 @@
   8.438    \end{tabular}
   8.439    \<^medskip>
   8.440  
   8.441 -  These other operations provide exclusive access for the particular
   8.442 -  kind of context (theory, proof, or generic context).  This interface
   8.443 -  observes the ML discipline for types and scopes: there is no other
   8.444 -  way to access the corresponding data slot of a context.  By keeping
   8.445 -  these operations private, an Isabelle/ML module may maintain
   8.446 -  abstract values authentically.\<close>
   8.447 +  These other operations provide exclusive access for the particular kind of
   8.448 +  context (theory, proof, or generic context). This interface observes the ML
   8.449 +  discipline for types and scopes: there is no other way to access the
   8.450 +  corresponding data slot of a context. By keeping these operations private,
   8.451 +  an Isabelle/ML module may maintain abstract values authentically.
   8.452 +\<close>
   8.453  
   8.454  text %mlref \<open>
   8.455    \begin{mldecls}
   8.456 @@ -359,22 +342,20 @@
   8.457    @{index_ML_functor Generic_Data} \\
   8.458    \end{mldecls}
   8.459  
   8.460 -  \<^descr> @{ML_functor Theory_Data}\<open>(spec)\<close> declares data for
   8.461 -  type @{ML_type theory} according to the specification provided as
   8.462 -  argument structure.  The resulting structure provides data init and
   8.463 -  access operations as described above.
   8.464 +  \<^descr> @{ML_functor Theory_Data}\<open>(spec)\<close> declares data for type @{ML_type theory}
   8.465 +  according to the specification provided as argument structure. The resulting
   8.466 +  structure provides data init and access operations as described above.
   8.467  
   8.468 -  \<^descr> @{ML_functor Proof_Data}\<open>(spec)\<close> is analogous to
   8.469 -  @{ML_functor Theory_Data} for type @{ML_type Proof.context}.
   8.470 +  \<^descr> @{ML_functor Proof_Data}\<open>(spec)\<close> is analogous to @{ML_functor Theory_Data}
   8.471 +  for type @{ML_type Proof.context}.
   8.472  
   8.473 -  \<^descr> @{ML_functor Generic_Data}\<open>(spec)\<close> is analogous to
   8.474 -  @{ML_functor Theory_Data} for type @{ML_type Context.generic}.
   8.475 -\<close>
   8.476 +  \<^descr> @{ML_functor Generic_Data}\<open>(spec)\<close> is analogous to @{ML_functor
   8.477 +  Theory_Data} for type @{ML_type Context.generic}. \<close>
   8.478  
   8.479  text %mlex \<open>
   8.480 -  The following artificial example demonstrates theory
   8.481 -  data: we maintain a set of terms that are supposed to be wellformed
   8.482 -  wrt.\ the enclosing theory.  The public interface is as follows:
   8.483 +  The following artificial example demonstrates theory data: we maintain a set
   8.484 +  of terms that are supposed to be wellformed wrt.\ the enclosing theory. The
   8.485 +  public interface is as follows:
   8.486  \<close>
   8.487  
   8.488  ML \<open>
   8.489 @@ -385,9 +366,10 @@
   8.490    end;
   8.491  \<close>
   8.492  
   8.493 -text \<open>The implementation uses private theory data internally, and
   8.494 -  only exposes an operation that involves explicit argument checking
   8.495 -  wrt.\ the given theory.\<close>
   8.496 +text \<open>
   8.497 +  The implementation uses private theory data internally, and only exposes an
   8.498 +  operation that involves explicit argument checking wrt.\ the given theory.
   8.499 +\<close>
   8.500  
   8.501  ML \<open>
   8.502    structure Wellformed_Terms: WELLFORMED_TERMS =
   8.503 @@ -414,59 +396,57 @@
   8.504    end;
   8.505  \<close>
   8.506  
   8.507 -text \<open>Type @{ML_type "term Ord_List.T"} is used for reasonably
   8.508 -  efficient representation of a set of terms: all operations are
   8.509 -  linear in the number of stored elements.  Here we assume that users
   8.510 -  of this module do not care about the declaration order, since that
   8.511 -  data structure forces its own arrangement of elements.
   8.512 +text \<open>
   8.513 +  Type @{ML_type "term Ord_List.T"} is used for reasonably efficient
   8.514 +  representation of a set of terms: all operations are linear in the number of
   8.515 +  stored elements. Here we assume that users of this module do not care about
   8.516 +  the declaration order, since that data structure forces its own arrangement
   8.517 +  of elements.
   8.518  
   8.519 -  Observe how the @{ML_text merge} operation joins the data slots of
   8.520 -  the two constituents: @{ML Ord_List.union} prevents duplication of
   8.521 -  common data from different branches, thus avoiding the danger of
   8.522 -  exponential blowup.  Plain list append etc.\ must never be used for
   8.523 -  theory data merges!
   8.524 +  Observe how the @{ML_text merge} operation joins the data slots of the two
   8.525 +  constituents: @{ML Ord_List.union} prevents duplication of common data from
   8.526 +  different branches, thus avoiding the danger of exponential blowup. Plain
   8.527 +  list append etc.\ must never be used for theory data merges!
   8.528  
   8.529    \<^medskip>
   8.530    Our intended invariant is achieved as follows:
   8.531  
   8.532 -  \<^enum> @{ML Wellformed_Terms.add} only admits terms that have passed
   8.533 -  the @{ML Sign.cert_term} check of the given theory at that point.
   8.534 -
   8.535 -  \<^enum> Wellformedness in the sense of @{ML Sign.cert_term} is
   8.536 -  monotonic wrt.\ the sub-theory relation.  So our data can move
   8.537 -  upwards in the hierarchy (via extension or merges), and maintain
   8.538 -  wellformedness without further checks.
   8.539 -
   8.540 +    \<^enum> @{ML Wellformed_Terms.add} only admits terms that have passed the @{ML
   8.541 +    Sign.cert_term} check of the given theory at that point.
   8.542 +  
   8.543 +    \<^enum> Wellformedness in the sense of @{ML Sign.cert_term} is monotonic wrt.\
   8.544 +    the sub-theory relation. So our data can move upwards in the hierarchy
   8.545 +    (via extension or merges), and maintain wellformedness without further
   8.546 +    checks.
   8.547  
   8.548 -  Note that all basic operations of the inference kernel (which
   8.549 -  includes @{ML Sign.cert_term}) observe this monotonicity principle,
   8.550 -  but other user-space tools don't.  For example, fully-featured
   8.551 -  type-inference via @{ML Syntax.check_term} (cf.\
   8.552 -  \secref{sec:term-check}) is not necessarily monotonic wrt.\ the
   8.553 -  background theory, since constraints of term constants can be
   8.554 -  modified by later declarations, for example.
   8.555 +  Note that all basic operations of the inference kernel (which includes @{ML
   8.556 +  Sign.cert_term}) observe this monotonicity principle, but other user-space
   8.557 +  tools don't. For example, fully-featured type-inference via @{ML
   8.558 +  Syntax.check_term} (cf.\ \secref{sec:term-check}) is not necessarily
   8.559 +  monotonic wrt.\ the background theory, since constraints of term constants
   8.560 +  can be modified by later declarations, for example.
   8.561  
   8.562 -  In most cases, user-space context data does not have to take such
   8.563 -  invariants too seriously.  The situation is different in the
   8.564 -  implementation of the inference kernel itself, which uses the very
   8.565 -  same data mechanisms for types, constants, axioms etc.
   8.566 +  In most cases, user-space context data does not have to take such invariants
   8.567 +  too seriously. The situation is different in the implementation of the
   8.568 +  inference kernel itself, which uses the very same data mechanisms for types,
   8.569 +  constants, axioms etc.
   8.570  \<close>
   8.571  
   8.572  
   8.573  subsection \<open>Configuration options \label{sec:config-options}\<close>
   8.574  
   8.575 -text \<open>A \<^emph>\<open>configuration option\<close> is a named optional value of
   8.576 -  some basic type (Boolean, integer, string) that is stored in the
   8.577 -  context.  It is a simple application of general context data
   8.578 -  (\secref{sec:context-data}) that is sufficiently common to justify
   8.579 -  customized setup, which includes some concrete declarations for
   8.580 -  end-users using existing notation for attributes (cf.\
   8.581 -  \secref{sec:attributes}).
   8.582 +text \<open>
   8.583 +  A \<^emph>\<open>configuration option\<close> is a named optional value of some basic type
   8.584 +  (Boolean, integer, string) that is stored in the context. It is a simple
   8.585 +  application of general context data (\secref{sec:context-data}) that is
   8.586 +  sufficiently common to justify customized setup, which includes some
   8.587 +  concrete declarations for end-users using existing notation for attributes
   8.588 +  (cf.\ \secref{sec:attributes}).
   8.589  
   8.590 -  For example, the predefined configuration option @{attribute
   8.591 -  show_types} controls output of explicit type constraints for
   8.592 -  variables in printed terms (cf.\ \secref{sec:read-print}).  Its
   8.593 -  value can be modified within Isar text like this:
   8.594 +  For example, the predefined configuration option @{attribute show_types}
   8.595 +  controls output of explicit type constraints for variables in printed terms
   8.596 +  (cf.\ \secref{sec:read-print}). Its value can be modified within Isar text
   8.597 +  like this:
   8.598  \<close>
   8.599  
   8.600  experiment
   8.601 @@ -489,16 +469,18 @@
   8.602  
   8.603  end
   8.604  
   8.605 -text \<open>Configuration options that are not set explicitly hold a
   8.606 -  default value that can depend on the application context.  This
   8.607 -  allows to retrieve the value from another slot within the context,
   8.608 -  or fall back on a global preference mechanism, for example.
   8.609 +text \<open>
   8.610 +  Configuration options that are not set explicitly hold a default value that
   8.611 +  can depend on the application context. This allows to retrieve the value
   8.612 +  from another slot within the context, or fall back on a global preference
   8.613 +  mechanism, for example.
   8.614  
   8.615 -  The operations to declare configuration options and get/map their
   8.616 -  values are modeled as direct replacements for historic global
   8.617 -  references, only that the context is made explicit.  This allows
   8.618 -  easy configuration of tools, without relying on the execution order
   8.619 -  as required for old-style mutable references.\<close>
   8.620 +  The operations to declare configuration options and get/map their values are
   8.621 +  modeled as direct replacements for historic global references, only that the
   8.622 +  context is made explicit. This allows easy configuration of tools, without
   8.623 +  relying on the execution order as required for old-style mutable
   8.624 +  references.
   8.625 +\<close>
   8.626  
   8.627  text %mlref \<open>
   8.628    \begin{mldecls}
   8.629 @@ -514,37 +496,38 @@
   8.630    string Config.T"} \\
   8.631    \end{mldecls}
   8.632  
   8.633 -  \<^descr> @{ML Config.get}~\<open>ctxt config\<close> gets the value of
   8.634 -  \<open>config\<close> in the given context.
   8.635 +  \<^descr> @{ML Config.get}~\<open>ctxt config\<close> gets the value of \<open>config\<close> in the given
   8.636 +  context.
   8.637  
   8.638 -  \<^descr> @{ML Config.map}~\<open>config f ctxt\<close> updates the context
   8.639 -  by updating the value of \<open>config\<close>.
   8.640 +  \<^descr> @{ML Config.map}~\<open>config f ctxt\<close> updates the context by updating the value
   8.641 +  of \<open>config\<close>.
   8.642  
   8.643 -  \<^descr> \<open>config =\<close>~@{ML Attrib.setup_config_bool}~\<open>name
   8.644 -  default\<close> creates a named configuration option of type @{ML_type
   8.645 -  bool}, with the given \<open>default\<close> depending on the application
   8.646 -  context.  The resulting \<open>config\<close> can be used to get/map its
   8.647 -  value in a given context.  There is an implicit update of the
   8.648 -  background theory that registers the option as attribute with some
   8.649 -  concrete syntax.
   8.650 +  \<^descr> \<open>config =\<close>~@{ML Attrib.setup_config_bool}~\<open>name default\<close> creates a named
   8.651 +  configuration option of type @{ML_type bool}, with the given \<open>default\<close>
   8.652 +  depending on the application context. The resulting \<open>config\<close> can be used to
   8.653 +  get/map its value in a given context. There is an implicit update of the
   8.654 +  background theory that registers the option as attribute with some concrete
   8.655 +  syntax.
   8.656  
   8.657    \<^descr> @{ML Attrib.config_int}, @{ML Attrib.config_real}, and @{ML
   8.658 -  Attrib.config_string} work like @{ML Attrib.config_bool}, but for
   8.659 -  types @{ML_type int} and @{ML_type string}, respectively.
   8.660 +  Attrib.config_string} work like @{ML Attrib.config_bool}, but for types
   8.661 +  @{ML_type int} and @{ML_type string}, respectively.
   8.662  \<close>
   8.663  
   8.664 -text %mlex \<open>The following example shows how to declare and use a
   8.665 -  Boolean configuration option called \<open>my_flag\<close> with constant
   8.666 -  default value @{ML false}.\<close>
   8.667 +text %mlex \<open>
   8.668 +  The following example shows how to declare and use a Boolean configuration
   8.669 +  option called \<open>my_flag\<close> with constant default value @{ML false}.
   8.670 +\<close>
   8.671  
   8.672  ML \<open>
   8.673    val my_flag =
   8.674      Attrib.setup_config_bool @{binding my_flag} (K false)
   8.675  \<close>
   8.676  
   8.677 -text \<open>Now the user can refer to @{attribute my_flag} in
   8.678 -  declarations, while ML tools can retrieve the current value from the
   8.679 -  context via @{ML Config.get}.\<close>
   8.680 +text \<open>
   8.681 +  Now the user can refer to @{attribute my_flag} in declarations, while ML
   8.682 +  tools can retrieve the current value from the context via @{ML Config.get}.
   8.683 +\<close>
   8.684  
   8.685  ML_val \<open>@{assert} (Config.get @{context} my_flag = false)\<close>
   8.686  
   8.687 @@ -561,8 +544,10 @@
   8.688    ML_val \<open>@{assert} (Config.get @{context} my_flag = true)\<close>
   8.689  end
   8.690  
   8.691 -text \<open>Here is another example involving ML type @{ML_type real}
   8.692 -  (floating-point numbers).\<close>
   8.693 +text \<open>
   8.694 +  Here is another example involving ML type @{ML_type real} (floating-point
   8.695 +  numbers).
   8.696 +\<close>
   8.697  
   8.698  ML \<open>
   8.699    val airspeed_velocity =
   8.700 @@ -575,62 +560,58 @@
   8.701  
   8.702  section \<open>Names \label{sec:names}\<close>
   8.703  
   8.704 -text \<open>In principle, a name is just a string, but there are various
   8.705 -  conventions for representing additional structure.  For example,
   8.706 -  ``\<open>Foo.bar.baz\<close>'' is considered as a long name consisting of
   8.707 -  qualifier \<open>Foo.bar\<close> and base name \<open>baz\<close>.  The
   8.708 -  individual constituents of a name may have further substructure,
   8.709 -  e.g.\ the string ``\<^verbatim>\<open>\<alpha>\<close>'' encodes as a single
   8.710 -  symbol (\secref{sec:symbols}).
   8.711 +text \<open>
   8.712 +  In principle, a name is just a string, but there are various conventions for
   8.713 +  representing additional structure. For example, ``\<open>Foo.bar.baz\<close>'' is
   8.714 +  considered as a long name consisting of qualifier \<open>Foo.bar\<close> and base name
   8.715 +  \<open>baz\<close>. The individual constituents of a name may have further substructure,
   8.716 +  e.g.\ the string ``\<^verbatim>\<open>\<alpha>\<close>'' encodes as a single symbol (\secref{sec:symbols}).
   8.717  
   8.718    \<^medskip>
   8.719 -  Subsequently, we shall introduce specific categories of
   8.720 -  names.  Roughly speaking these correspond to logical entities as
   8.721 -  follows:
   8.722 +  Subsequently, we shall introduce specific categories of names. Roughly
   8.723 +  speaking these correspond to logical entities as follows:
   8.724  
   8.725 -  \<^item> Basic names (\secref{sec:basic-name}): free and bound
   8.726 -  variables.
   8.727 +  \<^item> Basic names (\secref{sec:basic-name}): free and bound variables.
   8.728  
   8.729    \<^item> Indexed names (\secref{sec:indexname}): schematic variables.
   8.730  
   8.731 -  \<^item> Long names (\secref{sec:long-name}): constants of any kind
   8.732 -  (type constructors, term constants, other concepts defined in user
   8.733 -  space).  Such entities are typically managed via name spaces
   8.734 -  (\secref{sec:name-space}).
   8.735 +  \<^item> Long names (\secref{sec:long-name}): constants of any kind (type
   8.736 +  constructors, term constants, other concepts defined in user space). Such
   8.737 +  entities are typically managed via name spaces (\secref{sec:name-space}).
   8.738  \<close>
   8.739  
   8.740  
   8.741  subsection \<open>Basic names \label{sec:basic-name}\<close>
   8.742  
   8.743  text \<open>
   8.744 -  A \<^emph>\<open>basic name\<close> essentially consists of a single Isabelle
   8.745 -  identifier.  There are conventions to mark separate classes of basic
   8.746 -  names, by attaching a suffix of underscores: one underscore means
   8.747 -  \<^emph>\<open>internal name\<close>, two underscores means \<^emph>\<open>Skolem name\<close>,
   8.748 -  three underscores means \<^emph>\<open>internal Skolem name\<close>.
   8.749 +  A \<^emph>\<open>basic name\<close> essentially consists of a single Isabelle identifier. There
   8.750 +  are conventions to mark separate classes of basic names, by attaching a
   8.751 +  suffix of underscores: one underscore means \<^emph>\<open>internal name\<close>, two
   8.752 +  underscores means \<^emph>\<open>Skolem name\<close>, three underscores means \<^emph>\<open>internal Skolem
   8.753 +  name\<close>.
   8.754  
   8.755 -  For example, the basic name \<open>foo\<close> has the internal version
   8.756 -  \<open>foo_\<close>, with Skolem versions \<open>foo__\<close> and \<open>foo___\<close>, respectively.
   8.757 +  For example, the basic name \<open>foo\<close> has the internal version \<open>foo_\<close>, with
   8.758 +  Skolem versions \<open>foo__\<close> and \<open>foo___\<close>, respectively.
   8.759  
   8.760 -  These special versions provide copies of the basic name space, apart
   8.761 -  from anything that normally appears in the user text.  For example,
   8.762 -  system generated variables in Isar proof contexts are usually marked
   8.763 -  as internal, which prevents mysterious names like \<open>xaa\<close> to
   8.764 -  appear in human-readable text.
   8.765 +  These special versions provide copies of the basic name space, apart from
   8.766 +  anything that normally appears in the user text. For example, system
   8.767 +  generated variables in Isar proof contexts are usually marked as internal,
   8.768 +  which prevents mysterious names like \<open>xaa\<close> to appear in human-readable text.
   8.769  
   8.770    \<^medskip>
   8.771 -  Manipulating binding scopes often requires on-the-fly
   8.772 -  renamings.  A \<^emph>\<open>name context\<close> contains a collection of already
   8.773 -  used names.  The \<open>declare\<close> operation adds names to the
   8.774 -  context.
   8.775 +  Manipulating binding scopes often requires on-the-fly renamings. A \<^emph>\<open>name
   8.776 +  context\<close> contains a collection of already used names. The \<open>declare\<close>
   8.777 +  operation adds names to the context.
   8.778  
   8.779 -  The \<open>invents\<close> operation derives a number of fresh names from
   8.780 -  a given starting point.  For example, the first three names derived
   8.781 -  from \<open>a\<close> are \<open>a\<close>, \<open>b\<close>, \<open>c\<close>.
   8.782 +  The \<open>invents\<close> operation derives a number of fresh names from a given
   8.783 +  starting point. For example, the first three names derived from \<open>a\<close> are \<open>a\<close>,
   8.784 +  \<open>b\<close>, \<open>c\<close>.
   8.785  
   8.786 -  The \<open>variants\<close> operation produces fresh names by
   8.787 -  incrementing tentative names as base-26 numbers (with digits \<open>a..z\<close>) until all clashes are resolved.  For example, name \<open>foo\<close> results in variants \<open>fooa\<close>, \<open>foob\<close>, \<open>fooc\<close>, \dots, \<open>fooaa\<close>, \<open>fooab\<close> etc.; each renaming
   8.788 -  step picks the next unused variant from this sequence.
   8.789 +  The \<open>variants\<close> operation produces fresh names by incrementing tentative
   8.790 +  names as base-26 numbers (with digits \<open>a..z\<close>) until all clashes are
   8.791 +  resolved. For example, name \<open>foo\<close> results in variants \<open>fooa\<close>, \<open>foob\<close>,
   8.792 +  \<open>fooc\<close>, \dots, \<open>fooaa\<close>, \<open>fooab\<close> etc.; each renaming step picks the next
   8.793 +  unused variant from this sequence.
   8.794  \<close>
   8.795  
   8.796  text %mlref \<open>
   8.797 @@ -649,35 +630,35 @@
   8.798    @{index_ML Variable.names_of: "Proof.context -> Name.context"} \\
   8.799    \end{mldecls}
   8.800  
   8.801 -  \<^descr> @{ML Name.internal}~\<open>name\<close> produces an internal name
   8.802 -  by adding one underscore.
   8.803 +  \<^descr> @{ML Name.internal}~\<open>name\<close> produces an internal name by adding one
   8.804 +  underscore.
   8.805  
   8.806 -  \<^descr> @{ML Name.skolem}~\<open>name\<close> produces a Skolem name by
   8.807 -  adding two underscores.
   8.808 +  \<^descr> @{ML Name.skolem}~\<open>name\<close> produces a Skolem name by adding two underscores.
   8.809  
   8.810 -  \<^descr> Type @{ML_type Name.context} represents the context of already
   8.811 -  used names; the initial value is @{ML "Name.context"}.
   8.812 +  \<^descr> Type @{ML_type Name.context} represents the context of already used names;
   8.813 +  the initial value is @{ML "Name.context"}.
   8.814  
   8.815 -  \<^descr> @{ML Name.declare}~\<open>name\<close> enters a used name into the
   8.816 -  context.
   8.817 +  \<^descr> @{ML Name.declare}~\<open>name\<close> enters a used name into the context.
   8.818  
   8.819 -  \<^descr> @{ML Name.invent}~\<open>context name n\<close> produces \<open>n\<close> fresh names derived from \<open>name\<close>.
   8.820 +  \<^descr> @{ML Name.invent}~\<open>context name n\<close> produces \<open>n\<close> fresh names derived from
   8.821 +  \<open>name\<close>.
   8.822  
   8.823 -  \<^descr> @{ML Name.variant}~\<open>name context\<close> produces a fresh
   8.824 -  variant of \<open>name\<close>; the result is declared to the context.
   8.825 +  \<^descr> @{ML Name.variant}~\<open>name context\<close> produces a fresh variant of \<open>name\<close>; the
   8.826 +  result is declared to the context.
   8.827  
   8.828 -  \<^descr> @{ML Variable.names_of}~\<open>ctxt\<close> retrieves the context
   8.829 -  of declared type and term variable names.  Projecting a proof
   8.830 -  context down to a primitive name context is occasionally useful when
   8.831 -  invoking lower-level operations.  Regular management of ``fresh
   8.832 -  variables'' is done by suitable operations of structure @{ML_structure
   8.833 -  Variable}, which is also able to provide an official status of
   8.834 -  ``locally fixed variable'' within the logical environment (cf.\
   8.835 -  \secref{sec:variables}).
   8.836 +  \<^descr> @{ML Variable.names_of}~\<open>ctxt\<close> retrieves the context of declared type and
   8.837 +  term variable names. Projecting a proof context down to a primitive name
   8.838 +  context is occasionally useful when invoking lower-level operations. Regular
   8.839 +  management of ``fresh variables'' is done by suitable operations of
   8.840 +  structure @{ML_structure Variable}, which is also able to provide an
   8.841 +  official status of ``locally fixed variable'' within the logical environment
   8.842 +  (cf.\ \secref{sec:variables}).
   8.843  \<close>
   8.844  
   8.845 -text %mlex \<open>The following simple examples demonstrate how to produce
   8.846 -  fresh names from the initial @{ML Name.context}.\<close>
   8.847 +text %mlex \<open>
   8.848 +  The following simple examples demonstrate how to produce fresh names from
   8.849 +  the initial @{ML Name.context}.
   8.850 +\<close>
   8.851  
   8.852  ML_val \<open>
   8.853    val list1 = Name.invent Name.context "a" 5;
   8.854 @@ -712,36 +693,32 @@
   8.855  subsection \<open>Indexed names \label{sec:indexname}\<close>
   8.856  
   8.857  text \<open>
   8.858 -  An \<^emph>\<open>indexed name\<close> (or \<open>indexname\<close>) is a pair of a basic
   8.859 -  name and a natural number.  This representation allows efficient
   8.860 -  renaming by incrementing the second component only.  The canonical
   8.861 -  way to rename two collections of indexnames apart from each other is
   8.862 -  this: determine the maximum index \<open>maxidx\<close> of the first
   8.863 -  collection, then increment all indexes of the second collection by
   8.864 -  \<open>maxidx + 1\<close>; the maximum index of an empty collection is
   8.865 +  An \<^emph>\<open>indexed name\<close> (or \<open>indexname\<close>) is a pair of a basic name and a natural
   8.866 +  number. This representation allows efficient renaming by incrementing the
   8.867 +  second component only. The canonical way to rename two collections of
   8.868 +  indexnames apart from each other is this: determine the maximum index
   8.869 +  \<open>maxidx\<close> of the first collection, then increment all indexes of the second
   8.870 +  collection by \<open>maxidx + 1\<close>; the maximum index of an empty collection is
   8.871    \<open>-1\<close>.
   8.872  
   8.873 -  Occasionally, basic names are injected into the same pair type of
   8.874 -  indexed names: then \<open>(x, -1)\<close> is used to encode the basic
   8.875 -  name \<open>x\<close>.
   8.876 +  Occasionally, basic names are injected into the same pair type of indexed
   8.877 +  names: then \<open>(x, -1)\<close> is used to encode the basic name \<open>x\<close>.
   8.878  
   8.879    \<^medskip>
   8.880 -  Isabelle syntax observes the following rules for
   8.881 -  representing an indexname \<open>(x, i)\<close> as a packed string:
   8.882 +  Isabelle syntax observes the following rules for representing an indexname
   8.883 +  \<open>(x, i)\<close> as a packed string:
   8.884  
   8.885 -  \<^item> \<open>?x\<close> if \<open>x\<close> does not end with a digit and \<open>i = 0\<close>,
   8.886 +    \<^item> \<open>?x\<close> if \<open>x\<close> does not end with a digit and \<open>i = 0\<close>,
   8.887  
   8.888 -  \<^item> \<open>?xi\<close> if \<open>x\<close> does not end with a digit,
   8.889 +    \<^item> \<open>?xi\<close> if \<open>x\<close> does not end with a digit,
   8.890  
   8.891 -  \<^item> \<open>?x.i\<close> otherwise.
   8.892 -
   8.893 +    \<^item> \<open>?x.i\<close> otherwise.
   8.894  
   8.895 -  Indexnames may acquire large index numbers after several maxidx
   8.896 -  shifts have been applied.  Results are usually normalized towards
   8.897 -  \<open>0\<close> at certain checkpoints, notably at the end of a proof.
   8.898 -  This works by producing variants of the corresponding basic name
   8.899 -  components.  For example, the collection \<open>?x1, ?x7, ?x42\<close>
   8.900 -  becomes \<open>?x, ?xa, ?xb\<close>.
   8.901 +  Indexnames may acquire large index numbers after several maxidx shifts have
   8.902 +  been applied. Results are usually normalized towards \<open>0\<close> at certain
   8.903 +  checkpoints, notably at the end of a proof. This works by producing variants
   8.904 +  of the corresponding basic name components. For example, the collection
   8.905 +  \<open>?x1, ?x7, ?x42\<close> becomes \<open>?x, ?xa, ?xb\<close>.
   8.906  \<close>
   8.907  
   8.908  text %mlref \<open>
   8.909 @@ -749,36 +726,34 @@
   8.910    @{index_ML_type indexname: "string * int"} \\
   8.911    \end{mldecls}
   8.912  
   8.913 -  \<^descr> Type @{ML_type indexname} represents indexed names.  This is
   8.914 -  an abbreviation for @{ML_type "string * int"}.  The second component
   8.915 -  is usually non-negative, except for situations where \<open>(x,
   8.916 -  -1)\<close> is used to inject basic names into this type.  Other negative
   8.917 -  indexes should not be used.
   8.918 +  \<^descr> Type @{ML_type indexname} represents indexed names. This is an
   8.919 +  abbreviation for @{ML_type "string * int"}. The second component is usually
   8.920 +  non-negative, except for situations where \<open>(x, -1)\<close> is used to inject basic
   8.921 +  names into this type. Other negative indexes should not be used.
   8.922  \<close>
   8.923  
   8.924  
   8.925  subsection \<open>Long names \label{sec:long-name}\<close>
   8.926  
   8.927 -text \<open>A \<^emph>\<open>long name\<close> consists of a sequence of non-empty name
   8.928 -  components.  The packed representation uses a dot as separator, as
   8.929 -  in ``\<open>A.b.c\<close>''.  The last component is called \<^emph>\<open>base
   8.930 -  name\<close>, the remaining prefix is called \<^emph>\<open>qualifier\<close> (which may be
   8.931 -  empty).  The qualifier can be understood as the access path to the
   8.932 -  named entity while passing through some nested block-structure,
   8.933 -  although our free-form long names do not really enforce any strict
   8.934 -  discipline.
   8.935 +text \<open>
   8.936 +  A \<^emph>\<open>long name\<close> consists of a sequence of non-empty name components. The
   8.937 +  packed representation uses a dot as separator, as in ``\<open>A.b.c\<close>''. The last
   8.938 +  component is called \<^emph>\<open>base name\<close>, the remaining prefix is called
   8.939 +  \<^emph>\<open>qualifier\<close> (which may be empty). The qualifier can be understood as the
   8.940 +  access path to the named entity while passing through some nested
   8.941 +  block-structure, although our free-form long names do not really enforce any
   8.942 +  strict discipline.
   8.943  
   8.944 -  For example, an item named ``\<open>A.b.c\<close>'' may be understood as
   8.945 -  a local entity \<open>c\<close>, within a local structure \<open>b\<close>,
   8.946 -  within a global structure \<open>A\<close>.  In practice, long names
   8.947 -  usually represent 1--3 levels of qualification.  User ML code should
   8.948 -  not make any assumptions about the particular structure of long
   8.949 +  For example, an item named ``\<open>A.b.c\<close>'' may be understood as a local entity
   8.950 +  \<open>c\<close>, within a local structure \<open>b\<close>, within a global structure \<open>A\<close>. In
   8.951 +  practice, long names usually represent 1--3 levels of qualification. User ML
   8.952 +  code should not make any assumptions about the particular structure of long
   8.953    names!
   8.954  
   8.955 -  The empty name is commonly used as an indication of unnamed
   8.956 -  entities, or entities that are not entered into the corresponding
   8.957 -  name space, whenever this makes any sense.  The basic operations on
   8.958 -  long names map empty names again to empty names.
   8.959 +  The empty name is commonly used as an indication of unnamed entities, or
   8.960 +  entities that are not entered into the corresponding name space, whenever
   8.961 +  this makes any sense. The basic operations on long names map empty names
   8.962 +  again to empty names.
   8.963  \<close>
   8.964  
   8.965  text %mlref \<open>
   8.966 @@ -790,45 +765,42 @@
   8.967    @{index_ML Long_Name.explode: "string -> string list"} \\
   8.968    \end{mldecls}
   8.969  
   8.970 -  \<^descr> @{ML Long_Name.base_name}~\<open>name\<close> returns the base name
   8.971 -  of a long name.
   8.972 +  \<^descr> @{ML Long_Name.base_name}~\<open>name\<close> returns the base name of a long name.
   8.973  
   8.974 -  \<^descr> @{ML Long_Name.qualifier}~\<open>name\<close> returns the qualifier
   8.975 -  of a long name.
   8.976 +  \<^descr> @{ML Long_Name.qualifier}~\<open>name\<close> returns the qualifier of a long name.
   8.977  
   8.978 -  \<^descr> @{ML Long_Name.append}~\<open>name\<^sub>1 name\<^sub>2\<close> appends two long
   8.979 -  names.
   8.980 +  \<^descr> @{ML Long_Name.append}~\<open>name\<^sub>1 name\<^sub>2\<close> appen