Merge
authorpaulson <lp15@cam.ac.uk>
Tue Nov 10 14:43:29 2015 +0000 (2015-11-10)
changeset 616104f54d2759a0b
parent 61609 77b453bd616f
parent 61608 a0487caabb4a
child 61611 a9c0572109af
Merge
src/HOL/Decision_Procs/Approximation.thy
src/HOL/Decision_Procs/Ferrack.thy
src/HOL/Decision_Procs/MIR.thy
src/HOL/Library/Extended_Real.thy
src/HOL/Library/Formal_Power_Series.thy
src/HOL/Multivariate_Analysis/Complex_Analysis_Basics.thy
src/HOL/Multivariate_Analysis/Complex_Transcendental.thy
src/HOL/Multivariate_Analysis/PolyRoots.thy
src/HOL/Multivariate_Analysis/Weierstrass.thy
src/HOL/Probability/Binary_Product_Measure.thy
src/HOL/Probability/Giry_Monad.thy
src/HOL/Probability/Lebesgue_Measure.thy
src/HOL/Probability/Probability_Mass_Function.thy
src/HOL/Probability/Projective_Limit.thy
src/HOL/Probability/Radon_Nikodym.thy
src/HOL/Probability/Sigma_Algebra.thy
src/Pure/Concurrent/simple_thread.ML
src/Pure/Concurrent/simple_thread.scala
     1.1 --- a/Admin/components/components.sha1	Tue Nov 10 14:18:41 2015 +0000
     1.2 +++ b/Admin/components/components.sha1	Tue Nov 10 14:43:29 2015 +0000
     1.3 @@ -31,6 +31,9 @@
     1.4  eccff31931fb128c1dd522cfc85495c9b66e67af  Haskabelle-2015.tar.gz
     1.5  683acd94761ef460cca1a628f650355370de5afb  hol-light-bundle-0.5-126.tar.gz
     1.6  20b53cfc3ffc5b15c1eabc91846915b49b4c0367  isabelle_fonts-20151021.tar.gz
     1.7 +736844204b2ef83974cd9f0a215738b767958c41  isabelle_fonts-20151104.tar.gz
     1.8 +9502c1aea938021f154adadff254c5c55da344bd  isabelle_fonts-20151106.tar.gz
     1.9 +f5c63689a394b974ac0d365debda577c6fa31c07  isabelle_fonts-20151107.tar.gz
    1.10  8d83e433c1419e0c0cc5fd1762903d11b4a5752c  jdk-6u31.tar.gz
    1.11  38d2d2a91c66714c18430e136e7e5191af3996e6  jdk-7u11.tar.gz
    1.12  d765bc4ad2f34d494429b2a8c1563c49db224944  jdk-7u13.tar.gz
     2.1 --- a/Admin/components/main	Tue Nov 10 14:18:41 2015 +0000
     2.2 +++ b/Admin/components/main	Tue Nov 10 14:43:29 2015 +0000
     2.3 @@ -4,7 +4,7 @@
     2.4  e-1.8
     2.5  exec_process-1.0.3
     2.6  Haskabelle-2015
     2.7 -isabelle_fonts-20151021
     2.8 +isabelle_fonts-20151107
     2.9  jdk-8u66
    2.10  jedit_build-20151023
    2.11  jfreechart-1.0.14-1
     3.1 --- a/Admin/polyml/future/ROOT.ML	Tue Nov 10 14:18:41 2015 +0000
     3.2 +++ b/Admin/polyml/future/ROOT.ML	Tue Nov 10 14:43:29 2015 +0000
     3.3 @@ -101,7 +101,7 @@
     3.4  use "General/properties.ML";
     3.5  use "General/timing.ML";
     3.6  
     3.7 -use "Concurrent/simple_thread.ML";
     3.8 +use "Concurrent/standard_thread.ML";
     3.9  use "Concurrent/synchronized.ML";
    3.10  use "General/markup.ML";
    3.11  use "Concurrent/single_assignment.ML";
     4.1 --- a/NEWS	Tue Nov 10 14:18:41 2015 +0000
     4.2 +++ b/NEWS	Tue Nov 10 14:43:29 2015 +0000
     4.3 @@ -22,9 +22,17 @@
     4.4  * Toplevel theorem statement 'proposition' is another alias for
     4.5  'theorem'.
     4.6  
     4.7 +* Syntax for formal comments "-- text" now also supports the symbolic
     4.8 +form "\<comment> text". Command-line tool "isabelle update_cartouches -c" helps
     4.9 +to update old sources.
    4.10 +
    4.11  
    4.12  *** Prover IDE -- Isabelle/Scala/jEdit ***
    4.13  
    4.14 +* Completion of symbols via prefix of \<name> or \<^name> or \name is
    4.15 +always possible, independently of the language context. It is never
    4.16 +implicit: a popup will show up unconditionally.
    4.17 +
    4.18  * Improved scheduling for urgent print tasks (e.g. command state output,
    4.19  interactive queries) wrt. long-running background tasks.
    4.20  
    4.21 @@ -46,9 +54,12 @@
    4.22  
    4.23  * The State panel manages explicit proof state output, with jEdit action
    4.24  "isabelle.update-state" (shortcut S+ENTER) to trigger update according
    4.25 -to cursor position. Option "editor_output_state" controls implicit proof
    4.26 -state output in the Output panel: suppressing this reduces resource
    4.27 -requirements of prover time and GUI space.
    4.28 +to cursor position.
    4.29 +
    4.30 +* The Output panel no longer shows proof state output by default. This
    4.31 +reduces resource requirements of prover time and GUI space.
    4.32 +INCOMPATIBILITY, use the State panel instead or enable option
    4.33 +"editor_output_state".
    4.34  
    4.35  * Action "isabelle-emph" (with keyboard shortcut C+e LEFT) controls
    4.36  emphasized text style; the effect is visible in document output, not in
    4.37 @@ -75,12 +86,14 @@
    4.38  
    4.39  * There is a new short form for antiquotations with a single argument
    4.40  that is a cartouche: \<^name>\<open>...\<close> is equivalent to @{name \<open>...\<close>} and
    4.41 -\<open>...\<close> without control symbol is equivalent to @{cartouche \<open>...\<close>}. The
    4.42 +\<open>...\<close> without control symbol is equivalent to @{cartouche \<open>...\<close>}.
    4.43 +\<^name> without following cartouche is equivalent to @{name}. The
    4.44  standard Isabelle fonts provide glyphs to render important control
    4.45  symbols, e.g. "\<^verbatim>", "\<^emph>", "\<^bold>".
    4.46  
    4.47 -* System option "document_symbols" determines completion of Isabelle
    4.48 -symbols within document source.
    4.49 +* Antiquotations @{noindent}, @{smallskip}, @{medskip}, @{bigskip} with
    4.50 +corresponding control symbols \<^noindent>, \<^smallskip>, \<^medskip>, \<^bigskip> specify spacing formally, using
    4.51 +standard LaTeX macros of the same names.
    4.52  
    4.53  * Antiquotation @{cartouche} in Isabelle/Pure is the same as @{text}.
    4.54  Consequently, \<open>...\<close> without any decoration prints literal quasi-formal
    4.55 @@ -109,13 +122,6 @@
    4.56    \<^enum>  enumerate
    4.57    \<^descr>  description
    4.58  
    4.59 -* Text may contain control symbols for markup and formatting as follows:
    4.60 -
    4.61 -  \<^noindent>   \noindent
    4.62 -  \<^smallskip>   \smallskip
    4.63 -  \<^medskip>   \medskip
    4.64 -  \<^bigskip>   \bigskip
    4.65 -
    4.66  * Command 'text_raw' has been clarified: input text is processed as in
    4.67  'text' (with antiquotations and control symbols). The key difference is
    4.68  the lack of the surrounding isabelle markup environment in output.
    4.69 @@ -124,6 +130,9 @@
    4.70  recursively, adding appropriate text style markup. These are typically
    4.71  used in the short form \<^emph>\<open>...\<close> and \<^bold>\<open>...\<close>.
    4.72  
    4.73 +* Document antiquotation @{footnote} outputs LaTeX source recursively,
    4.74 +marked as \footnote{}. This is typically used in the short form \<^footnote>\<open>...\<close>.
    4.75 +
    4.76  
    4.77  *** Isar ***
    4.78  
    4.79 @@ -267,6 +276,14 @@
    4.80  
    4.81  *** Pure ***
    4.82  
    4.83 +* Qualifiers in locale expressions default to mandatory ('!') regardless
    4.84 +of the command. Previously, for 'locale' and 'sublocale' the default was
    4.85 +optional ('?'). The old synatx '!' has been discontinued.
    4.86 +INCOMPATIBILITY, remove '!' and add '?' as required.
    4.87 +
    4.88 +* Keyword 'rewrites' identifies rewrite morphisms in interpretation
    4.89 +commands.  Previously, the keyword was 'where'.  INCOMPATIBILITY.
    4.90 +
    4.91  * Command 'print_definitions' prints dependencies of definitional
    4.92  specifications. This functionality used to be part of 'print_theory'.
    4.93  
    4.94 @@ -485,11 +502,18 @@
    4.95  
    4.96  * Imperative_HOL: obsolete theory Legacy_Mrec has been removed.
    4.97  
    4.98 -* Library/Omega_Words_Fun: Infinite words modeled as functions nat => 'a.
    4.99 +* Library/Omega_Words_Fun: Infinite words modeled as functions nat =>
   4.100 +'a.
   4.101 +
   4.102 +* HOL-Statespace: command 'statespace' uses mandatory qualifier for
   4.103 +import of parent, as for general 'locale' expressions. INCOMPATIBILITY,
   4.104 +remove '!' and add '?' as required.
   4.105  
   4.106  
   4.107  *** ML ***
   4.108  
   4.109 +* Antiquotation @{undefined} or \<^undefined> inlines (raise Match).
   4.110 +
   4.111  * The auxiliary module Pure/display.ML has been eliminated. Its
   4.112  elementary thm print operations are now in Pure/more_thm.ML and thus
   4.113  called Thm.pretty_thm, Thm.string_of_thm etc. INCOMPATIBILITY.
   4.114 @@ -528,10 +552,14 @@
   4.115  
   4.116  *** System ***
   4.117  
   4.118 +* Global session timeout is multiplied by timeout_scale factor. This
   4.119 +allows to adjust large-scale tests (e.g. AFP) to overall hardware
   4.120 +performance.
   4.121 +
   4.122  * Property values in etc/symbols may contain spaces, if written with the
   4.123  replacement character "␣" (Unicode point 0x2324).  For example:
   4.124  
   4.125 -  \<star>  code: 0x0022c6  group: operator  font: Deja␣Vu␣Sans␣Mono
   4.126 +    \<star>  code: 0x0022c6  group: operator  font: Deja␣Vu␣Sans␣Mono
   4.127  
   4.128  * Command-line tool "isabelle update_then" expands old Isar command
   4.129  conflations:
   4.130 @@ -568,6 +596,9 @@
   4.131  * Bash shell function "jvmpath" has been renamed to "platform_path": it
   4.132  is relevant both for Poly/ML and JVM processes.
   4.133  
   4.134 +* Heap images are 10-15% smaller due to less wasteful persistent theory
   4.135 +content (using ML type theory_id instead of theory);
   4.136 +
   4.137  
   4.138  
   4.139  New in Isabelle2015 (May 2015)
     5.1 --- a/etc/options	Tue Nov 10 14:18:41 2015 +0000
     5.2 +++ b/etc/options	Tue Nov 10 14:43:29 2015 +0000
     5.3 @@ -92,6 +92,9 @@
     5.4  option timeout : real = 0
     5.5    -- "timeout for session build job (seconds > 0)"
     5.6  
     5.7 +option timeout_scale : real = 1.0
     5.8 +  -- "scale factor for session timeout"
     5.9 +
    5.10  option process_output_limit : int = 100
    5.11    -- "build process output limit in million characters (0 = unlimited)"
    5.12  
    5.13 @@ -140,7 +143,7 @@
    5.14  public option editor_continuous_checking : bool = true
    5.15    -- "continuous checking of proof document (visible and required parts)"
    5.16  
    5.17 -public option editor_output_state : bool = true
    5.18 +public option editor_output_state : bool = false
    5.19    -- "implicit output of proof state"
    5.20  
    5.21  option editor_execution_delay : real = 0.02
    5.22 @@ -164,5 +167,3 @@
    5.23  public option completion_limit : int = 40
    5.24    -- "limit for completion within the formal context"
    5.25  
    5.26 -public option document_symbols : bool = false
    5.27 -  -- "completion of Isabelle symbols within document source"
     6.1 --- a/etc/symbols	Tue Nov 10 14:18:41 2015 +0000
     6.2 +++ b/etc/symbols	Tue Nov 10 14:43:29 2015 +0000
     6.3 @@ -349,9 +349,11 @@
     6.4  \<some>                 code: 0x0003f5
     6.5  \<hole>                 code: 0x002311
     6.6  \<newline>              code: 0x0023ce
     6.7 +\<comment>              code: 0x002015  font: IsabelleText
     6.8  \<open>                 code: 0x002039  group: punctuation  font: IsabelleText  abbrev: <<
     6.9  \<close>                code: 0x00203a  group: punctuation  font: IsabelleText  abbrev: >>
    6.10  \<here>                 code: 0x002302  font: IsabelleText
    6.11 +\<^undefined>           code: 0x002756  group: control  font: IsabelleText
    6.12  \<^noindent>            code: 0x0021e4  group: control  font: IsabelleText
    6.13  \<^smallskip>           code: 0x002508  group: control  font: IsabelleText
    6.14  \<^medskip>             code: 0x002509  group: control  font: IsabelleText
    6.15 @@ -359,6 +361,7 @@
    6.16  \<^item>                code: 0x0025aa  group: control  font: IsabelleText
    6.17  \<^enum>                code: 0x0025b8  group: control  font: IsabelleText
    6.18  \<^descr>               code: 0x0027a7  group: control  font: IsabelleText
    6.19 +\<^footnote>            code: 0x00204b  group: control  font: IsabelleText
    6.20  \<^verbatim>            code: 0x0025a9  group: control  font: IsabelleText
    6.21  \<^emph>                code: 0x002217  group: control  font: IsabelleText
    6.22  \<^bold>                code: 0x002759  group: control  font: IsabelleText
     7.1 --- a/lib/Tools/update_cartouches	Tue Nov 10 14:18:41 2015 +0000
     7.2 +++ b/lib/Tools/update_cartouches	Tue Nov 10 14:43:29 2015 +0000
     7.3 @@ -15,6 +15,7 @@
     7.4    echo "Usage: isabelle $PRG [FILES|DIRS...]"
     7.5    echo
     7.6    echo "  Options are:"
     7.7 +  echo "    -c           replace comment marker \"--\" by symbol \"\\<comment>\""
     7.8    echo "    -t           replace @{text} antiquotations within text tokens"
     7.9    echo
    7.10    echo "  Recursively find .thy files and update theory syntax to use cartouches"
    7.11 @@ -30,11 +31,15 @@
    7.12  
    7.13  # options
    7.14  
    7.15 +COMMENT="false"
    7.16  TEXT="false"
    7.17  
    7.18 -while getopts "t" OPT
    7.19 +while getopts "ct" OPT
    7.20  do
    7.21    case "$OPT" in
    7.22 +    c)
    7.23 +      COMMENT="true"
    7.24 +      ;;
    7.25      t)
    7.26        TEXT="true"
    7.27        ;;
    7.28 @@ -57,4 +62,4 @@
    7.29  ## main
    7.30  
    7.31  find $SPECS -name \*.thy -print0 | \
    7.32 -  xargs -0 "$ISABELLE_TOOL" java isabelle.Update_Cartouches "$TEXT"
    7.33 +  xargs -0 "$ISABELLE_TOOL" java isabelle.Update_Cartouches "$COMMENT" "$TEXT"
     8.1 --- a/lib/fonts/IsabelleText.sfd	Tue Nov 10 14:18:41 2015 +0000
     8.2 +++ b/lib/fonts/IsabelleText.sfd	Tue Nov 10 14:43:29 2015 +0000
     8.3 @@ -19,7 +19,7 @@
     8.4  OS2_WeightWidthSlopeOnly: 0
     8.5  OS2_UseTypoMetrics: 1
     8.6  CreationTime: 1050361371
     8.7 -ModificationTime: 1445439176
     8.8 +ModificationTime: 1446896286
     8.9  PfmFamily: 17
    8.10  TTFWeight: 400
    8.11  TTFWidth: 5
    8.12 @@ -2241,11 +2241,11 @@
    8.13  DisplaySize: -96
    8.14  AntiAlias: 1
    8.15  FitToEm: 1
    8.16 -WinInfo: 9558 18 16
    8.17 +WinInfo: 9864 18 16
    8.18  BeginPrivate: 0
    8.19  EndPrivate
    8.20  TeXData: 1 0 0 631296 315648 210432 572416 -1048576 210432 783286 444596 497025 792723 393216 433062 380633 303038 157286 324010 404750 52429 2506097 1059062 262144
    8.21 -BeginChars: 1114189 1393
    8.22 +BeginChars: 1114189 1398
    8.23  
    8.24  StartChar: u10000
    8.25  Encoding: 65536 65536 0
    8.26 @@ -16604,69 +16604,32 @@
    8.27  
    8.28  StartChar: endash
    8.29  Encoding: 8211 8211 178
    8.30 -Width: 1233
    8.31 -Flags: W
    8.32 -TtInstrs:
    8.33 -PUSHB_7
    8.34 - 2
    8.35 - 182
    8.36 - 0
    8.37 - 253
    8.38 - 4
    8.39 - 1
    8.40 - 0
    8.41 -MDAP[rnd]
    8.42 -MDRP[rnd,white]
    8.43 -IUP[x]
    8.44 -SVTCA[y-axis]
    8.45 -SRP0
    8.46 -MIRP[rp0,min,rnd,grey]
    8.47 -MIRP[min,rnd,grey]
    8.48 -IUP[y]
    8.49 -EndTTInstrs
    8.50 -LayerCount: 2
    8.51 -Fore
    8.52 -SplineSet
    8.53 -0 633 m 1,0,-1
    8.54 - 1233 633 l 1,1,-1
    8.55 - 1233 492 l 1,2,-1
    8.56 - 0 492 l 1,3,-1
    8.57 - 0 633 l 1,0,-1
    8.58 -EndSplineSet
    8.59 -Validated: 1
    8.60 +Width: 1024
    8.61 +Flags: W
    8.62 +LayerCount: 2
    8.63 +Fore
    8.64 +SplineSet
    8.65 +100 633 m 1,0,-1
    8.66 + 924 633 l 1,1,-1
    8.67 + 924 489 l 1,2,-1
    8.68 + 100 489 l 1,3,-1
    8.69 + 100 633 l 1,0,-1
    8.70 +EndSplineSet
    8.71  EndChar
    8.72  
    8.73  StartChar: emdash
    8.74  Encoding: 8212 8212 179
    8.75 -Width: 1233
    8.76 -Flags: W
    8.77 -TtInstrs:
    8.78 -PUSHB_6
    8.79 - 2
    8.80 - 182
    8.81 - 0
    8.82 - 4
    8.83 - 1
    8.84 - 0
    8.85 -MDAP[rnd]
    8.86 -MDRP[rnd,grey]
    8.87 -IUP[x]
    8.88 -SVTCA[y-axis]
    8.89 -SRP0
    8.90 -MDRP[rp0,rnd,grey]
    8.91 -MIRP[min,rnd,grey]
    8.92 -IUP[y]
    8.93 -EndTTInstrs
    8.94 -LayerCount: 2
    8.95 -Fore
    8.96 -SplineSet
    8.97 -0 633 m 1,0,-1
    8.98 - 1233 633 l 1,1,-1
    8.99 - 1233 492 l 1,2,-1
   8.100 - 0 492 l 1,3,-1
   8.101 - 0 633 l 1,0,-1
   8.102 -EndSplineSet
   8.103 -Validated: 1
   8.104 +Width: 2048
   8.105 +Flags: W
   8.106 +LayerCount: 2
   8.107 +Fore
   8.108 +SplineSet
   8.109 +100 633 m 1,0,-1
   8.110 + 1948 633 l 1,1,-1
   8.111 + 1948 489 l 1,2,-1
   8.112 + 100 489 l 1,3,-1
   8.113 + 100 633 l 1,0,-1
   8.114 +EndSplineSet
   8.115  EndChar
   8.116  
   8.117  StartChar: quotedblleft
   8.118 @@ -61936,5 +61899,151 @@
   8.119   6 -78 l 1,112,-1
   8.120  EndSplineSet
   8.121  EndChar
   8.122 +
   8.123 +StartChar: afii00208
   8.124 +Encoding: 8213 8213 1393
   8.125 +Width: 2048
   8.126 +Flags: W
   8.127 +LayerCount: 2
   8.128 +Fore
   8.129 +SplineSet
   8.130 +0 633 m 1,0,-1
   8.131 + 2048 633 l 1,1,-1
   8.132 + 2048 489 l 1,2,-1
   8.133 + 0 489 l 1,3,-1
   8.134 + 0 633 l 1,0,-1
   8.135 +EndSplineSet
   8.136 +EndChar
   8.137 +
   8.138 +StartChar: uni204B
   8.139 +Encoding: 8267 8267 1394
   8.140 +Width: 1233
   8.141 +Flags: W
   8.142 +LayerCount: 2
   8.143 +Fore
   8.144 +SplineSet
   8.145 +651 1493 m 2,0,1
   8.146 + 866 1493 866 1493 996.5 1377 c 128,-1,2
   8.147 + 1127 1261 1127 1261 1127 1071 c 0,3,4
   8.148 + 1127 887 1127 887 1009 776.5 c 128,-1,5
   8.149 + 891 666 891 666 676 649 c 1,6,-1
   8.150 + 676 -197 l 1,7,-1
   8.151 + 535 -197 l 1,8,-1
   8.152 + 535 1370 l 1,9,-1
   8.153 + 344 1370 l 1,10,-1
   8.154 + 344 -197 l 1,11,-1
   8.155 + 203 -197 l 1,12,-1
   8.156 + 203 1493 l 1,13,-1
   8.157 + 651 1493 l 2,0,1
   8.158 +EndSplineSet
   8.159 +EndChar
   8.160 +
   8.161 +StartChar: uni2B1A
   8.162 +Encoding: 11034 11034 1395
   8.163 +Width: 1233
   8.164 +Flags: W
   8.165 +LayerCount: 2
   8.166 +Fore
   8.167 +SplineSet
   8.168 +1227 126 m 1,0,-1
   8.169 + 1227 -78 l 1,1,-1
   8.170 + 1022 -78 l 1,2,-1
   8.171 + 1022 36 l 1,3,-1
   8.172 + 1112 36 l 1,4,-1
   8.173 + 1112 126 l 1,5,-1
   8.174 + 1227 126 l 1,0,-1
   8.175 +1227 454 m 1,6,-1
   8.176 + 1227 280 l 1,7,-1
   8.177 + 1112 280 l 1,8,-1
   8.178 + 1112 454 l 1,9,-1
   8.179 + 1227 454 l 1,6,-1
   8.180 +1227 788 m 1,10,-1
   8.181 + 1227 609 l 1,11,-1
   8.182 + 1112 609 l 1,12,-1
   8.183 + 1112 788 l 1,13,-1
   8.184 + 1227 788 l 1,10,-1
   8.185 +868 36 m 1,14,-1
   8.186 + 868 -78 l 1,15,-1
   8.187 + 694 -78 l 1,16,-1
   8.188 + 694 36 l 1,17,-1
   8.189 + 868 36 l 1,14,-1
   8.190 +540 36 m 1,18,-1
   8.191 + 540 -78 l 1,19,-1
   8.192 + 360 -78 l 1,20,-1
   8.193 + 360 36 l 1,21,-1
   8.194 + 540 36 l 1,18,-1
   8.195 +120 126 m 1,22,-1
   8.196 + 120 36 l 1,23,-1
   8.197 + 206 36 l 1,24,-1
   8.198 + 206 -78 l 1,25,-1
   8.199 + 6 -78 l 1,26,-1
   8.200 + 6 126 l 1,27,-1
   8.201 + 120 126 l 1,22,-1
   8.202 +120 454 m 1,28,-1
   8.203 + 120 280 l 1,29,-1
   8.204 + 6 280 l 1,30,-1
   8.205 + 6 454 l 1,31,-1
   8.206 + 120 454 l 1,28,-1
   8.207 +120 788 m 1,32,-1
   8.208 + 120 609 l 1,33,-1
   8.209 + 6 609 l 1,34,-1
   8.210 + 6 788 l 1,35,-1
   8.211 + 120 788 l 1,32,-1
   8.212 +1227 1142 m 1,36,-1
   8.213 + 1227 942 l 1,37,-1
   8.214 + 1112 942 l 1,38,-1
   8.215 + 1112 1028 l 1,39,-1
   8.216 + 1022 1028 l 1,40,-1
   8.217 + 1022 1142 l 1,41,-1
   8.218 + 1227 1142 l 1,36,-1
   8.219 +868 1142 m 1,42,-1
   8.220 + 868 1028 l 1,43,-1
   8.221 + 694 1028 l 1,44,-1
   8.222 + 694 1142 l 1,45,-1
   8.223 + 868 1142 l 1,42,-1
   8.224 +540 1142 m 1,46,-1
   8.225 + 540 1028 l 1,47,-1
   8.226 + 360 1028 l 1,48,-1
   8.227 + 360 1142 l 1,49,-1
   8.228 + 540 1142 l 1,46,-1
   8.229 +206 1142 m 1,50,-1
   8.230 + 206 1028 l 1,51,-1
   8.231 + 120 1028 l 1,52,-1
   8.232 + 120 942 l 1,53,-1
   8.233 + 6 942 l 1,54,-1
   8.234 + 6 1142 l 1,55,-1
   8.235 + 206 1142 l 1,50,-1
   8.236 +EndSplineSet
   8.237 +EndChar
   8.238 +
   8.239 +StartChar: uni2756
   8.240 +Encoding: 10070 10070 1397
   8.241 +Width: 1233
   8.242 +Flags: W
   8.243 +LayerCount: 2
   8.244 +Fore
   8.245 +SplineSet
   8.246 +44 569 m 1,0,-1
   8.247 + 303 828 l 1,1,-1
   8.248 + 563 569 l 1,2,-1
   8.249 + 303 309 l 1,3,-1
   8.250 + 44 569 l 1,0,-1
   8.251 +670 569 m 1,4,-1
   8.252 + 930 827 l 1,5,-1
   8.253 + 1189 569 l 1,6,-1
   8.254 + 930 308 l 1,7,-1
   8.255 + 670 569 l 1,4,-1
   8.256 +358 879 m 1,8,-1
   8.257 + 618 1140 l 1,9,-1
   8.258 + 878 879 l 1,10,-1
   8.259 + 618 620 l 1,11,-1
   8.260 + 358 879 l 1,8,-1
   8.261 +358 254 m 1,12,-1
   8.262 + 618 514 l 1,13,-1
   8.263 + 878 254 l 1,14,-1
   8.264 + 618 -6 l 1,15,-1
   8.265 + 358 254 l 1,12,-1
   8.266 +EndSplineSet
   8.267 +EndChar
   8.268  EndChars
   8.269  EndSplineFont
     9.1 --- a/lib/fonts/IsabelleTextBold.sfd	Tue Nov 10 14:18:41 2015 +0000
     9.2 +++ b/lib/fonts/IsabelleTextBold.sfd	Tue Nov 10 14:43:29 2015 +0000
     9.3 @@ -20,7 +20,7 @@
     9.4  OS2_WeightWidthSlopeOnly: 0
     9.5  OS2_UseTypoMetrics: 1
     9.6  CreationTime: 1050374980
     9.7 -ModificationTime: 1445439141
     9.8 +ModificationTime: 1446896348
     9.9  PfmFamily: 17
    9.10  TTFWeight: 700
    9.11  TTFWidth: 5
    9.12 @@ -1678,10 +1678,10 @@
    9.13  DisplaySize: -96
    9.14  AntiAlias: 1
    9.15  FitToEm: 1
    9.16 -WinInfo: 9534 21 15
    9.17 +WinInfo: 9996 21 15
    9.18  BeginPrivate: 0
    9.19  EndPrivate
    9.20 -BeginChars: 1114115 1385
    9.21 +BeginChars: 1114115 1389
    9.22  
    9.23  StartChar: .notdef
    9.24  Encoding: 1114112 -1 0
    9.25 @@ -42258,63 +42258,31 @@
    9.26  
    9.27  StartChar: endash
    9.28  Encoding: 8211 8211 999
    9.29 -Width: 1233
    9.30 -Flags: W
    9.31 -TtInstrs:
    9.32 -PUSHB_5
    9.33 - 2
    9.34 - 0
    9.35 - 4
    9.36 - 1
    9.37 - 0
    9.38 -MDAP[rnd]
    9.39 -MDRP[min,rnd,white]
    9.40 -IUP[x]
    9.41 -SVTCA[y-axis]
    9.42 -SRP0
    9.43 -MDRP[rp0,rnd,grey]
    9.44 -MDRP[min,rnd,grey]
    9.45 -IUP[y]
    9.46 -EndTTInstrs
    9.47 -LayerCount: 2
    9.48 -Fore
    9.49 -SplineSet
    9.50 -0 690 m 1,0,-1
    9.51 - 1233 690 l 1,1,-1
    9.52 - 1233 444 l 1,2,-1
    9.53 - 0 444 l 1,3,-1
    9.54 - 0 690 l 1,0,-1
    9.55 +Width: 1024
    9.56 +Flags: W
    9.57 +LayerCount: 2
    9.58 +Fore
    9.59 +SplineSet
    9.60 +110 690 m 1,0,-1
    9.61 + 914 690 l 1,1,-1
    9.62 + 914 432 l 1,2,-1
    9.63 + 110 432 l 1,3,-1
    9.64 + 110 690 l 1,0,-1
    9.65  EndSplineSet
    9.66  EndChar
    9.67  
    9.68  StartChar: emdash
    9.69  Encoding: 8212 8212 1000
    9.70 -Width: 1233
    9.71 -Flags: W
    9.72 -TtInstrs:
    9.73 -PUSHB_5
    9.74 - 2
    9.75 - 0
    9.76 - 4
    9.77 - 1
    9.78 - 0
    9.79 -MDAP[rnd]
    9.80 -MDRP[min,rnd,grey]
    9.81 -IUP[x]
    9.82 -SVTCA[y-axis]
    9.83 -SRP0
    9.84 -MDRP[rp0,rnd,grey]
    9.85 -MDRP[min,rnd,grey]
    9.86 -IUP[y]
    9.87 -EndTTInstrs
    9.88 -LayerCount: 2
    9.89 -Fore
    9.90 -SplineSet
    9.91 -0 690 m 1,0,-1
    9.92 - 1233 690 l 1,1,-1
    9.93 - 1233 444 l 1,2,-1
    9.94 - 0 444 l 1,3,-1
    9.95 - 0 690 l 1,0,-1
    9.96 +Width: 2048
    9.97 +Flags: W
    9.98 +LayerCount: 2
    9.99 +Fore
   9.100 +SplineSet
   9.101 +110 690 m 1,0,-1
   9.102 + 1938 690 l 1,1,-1
   9.103 + 1938 432 l 1,2,-1
   9.104 + 110 432 l 1,3,-1
   9.105 + 110 690 l 1,0,-1
   9.106  EndSplineSet
   9.107  EndChar
   9.108  
   9.109 @@ -68173,5 +68141,151 @@
   9.110   6 -78 l 1,112,-1
   9.111  EndSplineSet
   9.112  EndChar
   9.113 +
   9.114 +StartChar: afii00208
   9.115 +Encoding: 8213 8213 1385
   9.116 +Width: 2048
   9.117 +Flags: W
   9.118 +LayerCount: 2
   9.119 +Fore
   9.120 +SplineSet
   9.121 +0 690 m 1,0,-1
   9.122 + 2048 690 l 1,1,-1
   9.123 + 2048 432 l 1,2,-1
   9.124 + 0 432 l 1,3,-1
   9.125 + 0 690 l 1,0,-1
   9.126 +EndSplineSet
   9.127 +EndChar
   9.128 +
   9.129 +StartChar: uni204B
   9.130 +Encoding: 8267 8267 1386
   9.131 +Width: 1233
   9.132 +Flags: W
   9.133 +LayerCount: 2
   9.134 +Fore
   9.135 +SplineSet
   9.136 +688 1493 m 2,0,1
   9.137 + 903 1493 903 1493 1033 1377 c 128,-1,2
   9.138 + 1163 1261 1163 1261 1163 1071 c 0,3,4
   9.139 + 1163 893 1163 893 1052.5 783.5 c 128,-1,5
   9.140 + 942 674 942 674 737 649 c 1,6,-1
   9.141 + 737 -197 l 1,7,-1
   9.142 + 549 -197 l 1,8,-1
   9.143 + 549 1346 l 1,9,-1
   9.144 + 359 1346 l 1,10,-1
   9.145 + 359 -197 l 1,11,-1
   9.146 + 168 -197 l 1,12,-1
   9.147 + 168 1493 l 1,13,-1
   9.148 + 688 1493 l 2,0,1
   9.149 +EndSplineSet
   9.150 +EndChar
   9.151 +
   9.152 +StartChar: uni2B1A
   9.153 +Encoding: 11034 11034 1387
   9.154 +Width: 1233
   9.155 +Flags: W
   9.156 +LayerCount: 2
   9.157 +Fore
   9.158 +SplineSet
   9.159 +1227 126 m 1,0,-1
   9.160 + 1227 -78 l 1,1,-1
   9.161 + 1022 -78 l 1,2,-1
   9.162 + 1022 36 l 1,3,-1
   9.163 + 1112 36 l 1,4,-1
   9.164 + 1112 126 l 1,5,-1
   9.165 + 1227 126 l 1,0,-1
   9.166 +1227 454 m 1,6,-1
   9.167 + 1227 280 l 1,7,-1
   9.168 + 1112 280 l 1,8,-1
   9.169 + 1112 454 l 1,9,-1
   9.170 + 1227 454 l 1,6,-1
   9.171 +1227 788 m 1,10,-1
   9.172 + 1227 609 l 1,11,-1
   9.173 + 1112 609 l 1,12,-1
   9.174 + 1112 788 l 1,13,-1
   9.175 + 1227 788 l 1,10,-1
   9.176 +868 36 m 1,14,-1
   9.177 + 868 -78 l 1,15,-1
   9.178 + 694 -78 l 1,16,-1
   9.179 + 694 36 l 1,17,-1
   9.180 + 868 36 l 1,14,-1
   9.181 +540 36 m 1,18,-1
   9.182 + 540 -78 l 1,19,-1
   9.183 + 360 -78 l 1,20,-1
   9.184 + 360 36 l 1,21,-1
   9.185 + 540 36 l 1,18,-1
   9.186 +120 126 m 1,22,-1
   9.187 + 120 36 l 1,23,-1
   9.188 + 206 36 l 1,24,-1
   9.189 + 206 -78 l 1,25,-1
   9.190 + 6 -78 l 1,26,-1
   9.191 + 6 126 l 1,27,-1
   9.192 + 120 126 l 1,22,-1
   9.193 +120 454 m 1,28,-1
   9.194 + 120 280 l 1,29,-1
   9.195 + 6 280 l 1,30,-1
   9.196 + 6 454 l 1,31,-1
   9.197 + 120 454 l 1,28,-1
   9.198 +120 788 m 1,32,-1
   9.199 + 120 609 l 1,33,-1
   9.200 + 6 609 l 1,34,-1
   9.201 + 6 788 l 1,35,-1
   9.202 + 120 788 l 1,32,-1
   9.203 +1227 1142 m 1,36,-1
   9.204 + 1227 942 l 1,37,-1
   9.205 + 1112 942 l 1,38,-1
   9.206 + 1112 1028 l 1,39,-1
   9.207 + 1022 1028 l 1,40,-1
   9.208 + 1022 1142 l 1,41,-1
   9.209 + 1227 1142 l 1,36,-1
   9.210 +868 1142 m 1,42,-1
   9.211 + 868 1028 l 1,43,-1
   9.212 + 694 1028 l 1,44,-1
   9.213 + 694 1142 l 1,45,-1
   9.214 + 868 1142 l 1,42,-1
   9.215 +540 1142 m 1,46,-1
   9.216 + 540 1028 l 1,47,-1
   9.217 + 360 1028 l 1,48,-1
   9.218 + 360 1142 l 1,49,-1
   9.219 + 540 1142 l 1,46,-1
   9.220 +206 1142 m 1,50,-1
   9.221 + 206 1028 l 1,51,-1
   9.222 + 120 1028 l 1,52,-1
   9.223 + 120 942 l 1,53,-1
   9.224 + 6 942 l 1,54,-1
   9.225 + 6 1142 l 1,55,-1
   9.226 + 206 1142 l 1,50,-1
   9.227 +EndSplineSet
   9.228 +EndChar
   9.229 +
   9.230 +StartChar: uni2756
   9.231 +Encoding: 10070 10070 1388
   9.232 +Width: 1233
   9.233 +Flags: W
   9.234 +LayerCount: 2
   9.235 +Fore
   9.236 +SplineSet
   9.237 +44 569 m 1,0,-1
   9.238 + 303 828 l 1,1,-1
   9.239 + 563 569 l 1,2,-1
   9.240 + 303 309 l 1,3,-1
   9.241 + 44 569 l 1,0,-1
   9.242 +670 569 m 1,4,-1
   9.243 + 930 827 l 1,5,-1
   9.244 + 1189 569 l 1,6,-1
   9.245 + 930 308 l 1,7,-1
   9.246 + 670 569 l 1,4,-1
   9.247 +358 879 m 1,8,-1
   9.248 + 618 1140 l 1,9,-1
   9.249 + 878 879 l 1,10,-1
   9.250 + 618 620 l 1,11,-1
   9.251 + 358 879 l 1,8,-1
   9.252 +358 254 m 1,12,-1
   9.253 + 618 514 l 1,13,-1
   9.254 + 878 254 l 1,14,-1
   9.255 + 618 -6 l 1,15,-1
   9.256 + 358 254 l 1,12,-1
   9.257 +EndSplineSet
   9.258 +EndChar
   9.259  EndChars
   9.260  EndSplineFont
    10.1 --- a/lib/texinputs/isabelle.sty	Tue Nov 10 14:18:41 2015 +0000
    10.2 +++ b/lib/texinputs/isabelle.sty	Tue Nov 10 14:43:29 2015 +0000
    10.3 @@ -39,11 +39,6 @@
    10.4  \DeclareRobustCommand{\isactrlesup}{\egroup\egroup\endmath\egroup}
    10.5  \newcommand{\isactrlbold}[1]{{\bfseries\upshape\boldmath#1}}
    10.6  
    10.7 -\def\isactrlnoindent{\noindent}
    10.8 -\def\isactrlsmallskip{\smallskip}
    10.9 -\def\isactrlmedskip{\medskip}
   10.10 -\def\isactrlbigskip{\bigskip}
   10.11 -
   10.12  \newcommand{\isaantiqcontrol}[1]{\isatt{{\char`\\}{\char`\<}{\char`\^}#1{\char`\>}}}
   10.13  \newenvironment{isaantiq}{{\isacharat\isacharbraceleft}}{{\isacharbraceright}}
   10.14  
    11.1 --- a/lib/texinputs/isabellesym.sty	Tue Nov 10 14:18:41 2015 +0000
    11.2 +++ b/lib/texinputs/isabellesym.sty	Tue Nov 10 14:43:29 2015 +0000
    11.3 @@ -358,3 +358,4 @@
    11.4  \newcommand{\isasymclose}{\isatext{\raise.3ex\hbox{$\scriptscriptstyle\rangle$}}}
    11.5  \newcommand{\isasymhole}{\isatext{\rm\wasylozenge}}  %requires wasysym
    11.6  \newcommand{\isasymnewline}{\isatext{\fbox{$\hookleftarrow$}}}
    11.7 +\newcommand{\isasymcomment}{\isatext{---}}
    12.1 --- a/src/Doc/Classes/Classes.thy	Tue Nov 10 14:18:41 2015 +0000
    12.2 +++ b/src/Doc/Classes/Classes.thy	Tue Nov 10 14:43:29 2015 +0000
    12.3 @@ -457,7 +457,7 @@
    12.4    "replicate 0 _ = []"
    12.5    | "replicate (Suc n) xs = xs @ replicate n xs"
    12.6  
    12.7 -interpretation %quote list_monoid: monoid append "[]" where
    12.8 +interpretation %quote list_monoid: monoid append "[]" rewrites
    12.9    "monoid.pow_nat append [] = replicate"
   12.10  proof -
   12.11    interpret monoid append "[]" ..
    13.1 --- a/src/Doc/Codegen/Further.thy	Tue Nov 10 14:18:41 2015 +0000
    13.2 +++ b/src/Doc/Codegen/Further.thy	Tue Nov 10 14:43:29 2015 +0000
    13.3 @@ -202,7 +202,7 @@
    13.4    The interpretation itself is enriched with an equation @{text "t = c"}:
    13.5  \<close>
    13.6  
    13.7 -interpretation %quote fun_power: power "(\<lambda>n (f :: 'a \<Rightarrow> 'a). f ^^ n)" where
    13.8 +interpretation %quote fun_power: power "(\<lambda>n (f :: 'a \<Rightarrow> 'a). f ^^ n)" rewrites
    13.9    "power.powers (\<lambda>n f. f ^^ n) = funpows"
   13.10    by unfold_locales
   13.11      (simp_all add: fun_eq_iff funpow_mult mult.commute funpows_def)
    14.1 --- a/src/Doc/Eisbach/Manual.thy	Tue Nov 10 14:18:41 2015 +0000
    14.2 +++ b/src/Doc/Eisbach/Manual.thy	Tue Nov 10 14:43:29 2015 +0000
    14.3 @@ -14,8 +14,8 @@
    14.4    terms, facts, or other methods.
    14.5  
    14.6    \<^medskip>
    14.7 -  The syntax diagram below refers to some syntactic categories that
    14.8 -  are further defined in @{cite "isabelle-isar-ref"}.
    14.9 +  The syntax diagram below refers to some syntactic categories that are
   14.10 +  further defined in @{cite "isabelle-isar-ref"}.
   14.11  
   14.12    @{rail \<open>
   14.13      @@{command method} name args @'=' method
   14.14 @@ -56,11 +56,10 @@
   14.15        by prop_solver\<^sub>1
   14.16  
   14.17  text \<open>
   14.18 -  In this example, the facts \<open>impI\<close> and \<open>conjE\<close> are static. They
   14.19 -  are evaluated once when the method is defined and cannot be changed later.
   14.20 -  This makes the method stable in the sense of \<^emph>\<open>static scoping\<close>: naming
   14.21 -  another fact \<open>impI\<close> in a later context won't affect the behaviour of
   14.22 -  \<open>prop_solver\<^sub>1\<close>.
   14.23 +  In this example, the facts \<open>impI\<close> and \<open>conjE\<close> are static. They are evaluated
   14.24 +  once when the method is defined and cannot be changed later. This makes the
   14.25 +  method stable in the sense of \<^emph>\<open>static scoping\<close>: naming another fact \<open>impI\<close>
   14.26 +  in a later context won't affect the behaviour of \<open>prop_solver\<^sub>1\<close>.
   14.27  \<close>
   14.28  
   14.29  
   14.30 @@ -100,11 +99,11 @@
   14.31  subsection \<open>Named theorems\<close>
   14.32  
   14.33  text \<open>
   14.34 -  A \<open>named theorem\<close> is a fact whose contents are produced dynamically
   14.35 -  within the current proof context. The Isar command @{command_ref
   14.36 -  "named_theorems"} provides simple access to this concept: it declares a
   14.37 -  dynamic fact with corresponding \<^emph>\<open>attribute\<close> for managing
   14.38 -  this particular data slot in the context.
   14.39 +  A \<^emph>\<open>named theorem\<close> is a fact whose contents are produced dynamically within
   14.40 +  the current proof context. The Isar command @{command_ref "named_theorems"}
   14.41 +  provides simple access to this concept: it declares a dynamic fact with
   14.42 +  corresponding \<^emph>\<open>attribute\<close> for managing this particular data slot in the
   14.43 +  context.
   14.44  \<close>
   14.45  
   14.46      named_theorems intros
   14.47 @@ -112,7 +111,8 @@
   14.48  text \<open>
   14.49    So far \<open>intros\<close> refers to the empty fact. Using the Isar command
   14.50    @{command_ref "declare"} we may apply declaration attributes to the context.
   14.51 -  Below we declare both \<open>conjI\<close> and \<open>impI\<close> as \<open>intros\<close>, adding them to the named theorem slot.
   14.52 +  Below we declare both \<open>conjI\<close> and \<open>impI\<close> as \<open>intros\<close>, adding them to the
   14.53 +  named theorem slot.
   14.54  \<close>
   14.55  
   14.56      declare conjI [intros] and impI [intros]
   14.57 @@ -136,8 +136,8 @@
   14.58  text \<open>
   14.59    Often these named theorems need to be augmented on the spot, when a method
   14.60    is invoked. The @{keyword_def "declares"} keyword in the signature of
   14.61 -  @{command method} adds the common method syntax \<open>method decl: facts\<close>
   14.62 -  for each named theorem \<open>decl\<close>.
   14.63 +  @{command method} adds the common method syntax \<open>method decl: facts\<close> for
   14.64 +  each named theorem \<open>decl\<close>.
   14.65  \<close>
   14.66  
   14.67      method prop_solver\<^sub>4 declares intros elims =
   14.68 @@ -170,11 +170,12 @@
   14.69  section \<open>Higher-order methods\<close>
   14.70  
   14.71  text \<open>
   14.72 -  The \<^emph>\<open>structured concatenation\<close> combinator ``\<open>method\<^sub>1 ;
   14.73 -  method\<^sub>2\<close>'' was introduced in Isabelle2015, motivated by development of
   14.74 -  Eisbach. It is similar to ``\<open>method\<^sub>1, method\<^sub>2\<close>'', but \<open>method\<^sub>2\<close> is invoked on on \<^emph>\<open>all\<close> subgoals that have newly emerged from
   14.75 -  \<open>method\<^sub>1\<close>. This is useful to handle cases where the number of
   14.76 -  subgoals produced by a method is determined dynamically at run-time.
   14.77 +  The \<^emph>\<open>structured concatenation\<close> combinator ``\<open>method\<^sub>1 ; method\<^sub>2\<close>'' was
   14.78 +  introduced in Isabelle2015, motivated by development of Eisbach. It is
   14.79 +  similar to ``\<open>method\<^sub>1, method\<^sub>2\<close>'', but \<open>method\<^sub>2\<close> is invoked on on \<^emph>\<open>all\<close>
   14.80 +  subgoals that have newly emerged from \<open>method\<^sub>1\<close>. This is useful to handle
   14.81 +  cases where the number of subgoals produced by a method is determined
   14.82 +  dynamically at run-time.
   14.83  \<close>
   14.84  
   14.85      method conj_with uses rule =
   14.86 @@ -190,18 +191,17 @@
   14.87    method combinators with prefix syntax. For example, to more usefully exploit
   14.88    Isabelle's backtracking, the explicit requirement that a method solve all
   14.89    produced subgoals is frequently useful. This can easily be written as a
   14.90 -  \<^emph>\<open>higher-order method\<close> using ``\<open>;\<close>''. The @{keyword "methods"}
   14.91 -  keyword denotes method parameters that are other proof methods to be invoked
   14.92 -  by the method being defined.
   14.93 +  \<^emph>\<open>higher-order method\<close> using ``\<open>;\<close>''. The @{keyword "methods"} keyword
   14.94 +  denotes method parameters that are other proof methods to be invoked by the
   14.95 +  method being defined.
   14.96  \<close>
   14.97  
   14.98      method solve methods m = (m ; fail)
   14.99  
  14.100  text \<open>
  14.101 -  Given some method-argument \<open>m\<close>, \<open>solve \<open>m\<close>\<close> applies the
  14.102 -  method \<open>m\<close> and then fails whenever \<open>m\<close> produces any new unsolved
  14.103 -  subgoals --- i.e. when \<open>m\<close> fails to completely discharge the goal it
  14.104 -  was applied to.
  14.105 +  Given some method-argument \<open>m\<close>, \<open>solve \<open>m\<close>\<close> applies the method \<open>m\<close> and then
  14.106 +  fails whenever \<open>m\<close> produces any new unsolved subgoals --- i.e. when \<open>m\<close>
  14.107 +  fails to completely discharge the goal it was applied to.
  14.108  \<close>
  14.109  
  14.110  
  14.111 @@ -222,41 +222,43 @@
  14.112          (erule notE ; solve \<open>prop_solver\<close>))+
  14.113  
  14.114  text \<open>
  14.115 -  The only non-trivial part above is the final alternative \<open>(erule notE
  14.116 -  ; solve \<open>prop_solver\<close>)\<close>. Here, in the case that all other alternatives
  14.117 -  fail, the method takes one of the assumptions @{term "\<not> P"} of the current
  14.118 -  goal and eliminates it with the rule \<open>notE\<close>, causing the goal to be
  14.119 -  proved to become @{term P}. The method then recursively invokes itself on
  14.120 -  the remaining goals. The job of the recursive call is to demonstrate that
  14.121 -  there is a contradiction in the original assumptions (i.e.\ that @{term P}
  14.122 -  can be derived from them). Note this recursive invocation is applied with
  14.123 -  the @{method solve} method combinator to ensure that a contradiction will
  14.124 -  indeed be shown. In the case where a contradiction cannot be found,
  14.125 -  backtracking will occur and a different assumption @{term "\<not> Q"} will be
  14.126 -  chosen for elimination.
  14.127 +  The only non-trivial part above is the final alternative \<open>(erule notE ;
  14.128 +  solve \<open>prop_solver\<close>)\<close>. Here, in the case that all other alternatives fail,
  14.129 +  the method takes one of the assumptions @{term "\<not> P"} of the current goal
  14.130 +  and eliminates it with the rule \<open>notE\<close>, causing the goal to be proved to
  14.131 +  become @{term P}. The method then recursively invokes itself on the
  14.132 +  remaining goals. The job of the recursive call is to demonstrate that there
  14.133 +  is a contradiction in the original assumptions (i.e.\ that @{term P} can be
  14.134 +  derived from them). Note this recursive invocation is applied with the
  14.135 +  @{method solve} method combinator to ensure that a contradiction will indeed
  14.136 +  be shown. In the case where a contradiction cannot be found, backtracking
  14.137 +  will occur and a different assumption @{term "\<not> Q"} will be chosen for
  14.138 +  elimination.
  14.139  
  14.140    Note that the recursive call to @{method prop_solver} does not have any
  14.141 -  parameters passed to it. Recall that fact parameters, e.g.\ \<open>intros\<close>, \<open>elims\<close>, and \<open>subst\<close>, are managed by declarations
  14.142 -  in the current proof context. They will therefore be passed to any recursive
  14.143 -  call to @{method prop_solver} and, more generally, any invocation of a
  14.144 -  method which declares these named theorems.
  14.145 +  parameters passed to it. Recall that fact parameters, e.g.\ \<open>intros\<close>,
  14.146 +  \<open>elims\<close>, and \<open>subst\<close>, are managed by declarations in the current proof
  14.147 +  context. They will therefore be passed to any recursive call to @{method
  14.148 +  prop_solver} and, more generally, any invocation of a method which declares
  14.149 +  these named theorems.
  14.150  
  14.151    \<^medskip>
  14.152    After declaring some standard rules to the context, the @{method
  14.153    prop_solver} becomes capable of solving non-trivial propositional
  14.154 -  tautologies.\<close>
  14.155 +  tautologies.
  14.156 +\<close>
  14.157  
  14.158      lemmas [intros] =
  14.159 -      conjI  --  \<open>@{thm conjI}\<close>
  14.160 -      impI  --  \<open>@{thm impI}\<close>
  14.161 -      disjCI  --  \<open>@{thm disjCI}\<close>
  14.162 -      iffI  --  \<open>@{thm iffI}\<close>
  14.163 -      notI  --  \<open>@{thm notI}\<close>
  14.164 +      conjI  \<comment>  \<open>@{thm conjI}\<close>
  14.165 +      impI  \<comment>  \<open>@{thm impI}\<close>
  14.166 +      disjCI  \<comment>  \<open>@{thm disjCI}\<close>
  14.167 +      iffI  \<comment>  \<open>@{thm iffI}\<close>
  14.168 +      notI  \<comment>  \<open>@{thm notI}\<close>
  14.169  
  14.170      lemmas [elims] =
  14.171 -      impCE  --  \<open>@{thm impCE}\<close>
  14.172 -      conjE  --  \<open>@{thm conjE}\<close>
  14.173 -      disjE  --  \<open>@{thm disjE}\<close>
  14.174 +      impCE  \<comment>  \<open>@{thm impCE}\<close>
  14.175 +      conjE  \<comment>  \<open>@{thm conjE}\<close>
  14.176 +      disjE  \<comment>  \<open>@{thm disjE}\<close>
  14.177  
  14.178      lemma "(A \<or> B) \<and> (A \<longrightarrow> C) \<and> (B \<longrightarrow> C) \<longrightarrow> C"
  14.179        by prop_solver
  14.180 @@ -271,15 +273,15 @@
  14.181    result of backtracking. When designing more sophisticated proof methods this
  14.182    proves too restrictive and difficult to manage conceptually.
  14.183  
  14.184 -  To address this, we introduce the @{method_def "match"} method, which
  14.185 -  provides more direct access to the higher-order matching facility at the
  14.186 -  core of Isabelle. It is implemented as a separate proof method (in
  14.187 -  Isabelle/ML), and thus can be directly applied to proofs, however it is most
  14.188 -  useful when applied in the context of writing Eisbach method definitions.
  14.189 +  To address this, we introduce the @{method_def match} method, which provides
  14.190 +  more direct access to the higher-order matching facility at the core of
  14.191 +  Isabelle. It is implemented as a separate proof method (in Isabelle/ML), and
  14.192 +  thus can be directly applied to proofs, however it is most useful when
  14.193 +  applied in the context of writing Eisbach method definitions.
  14.194  
  14.195    \<^medskip>
  14.196 -  The syntax diagram below refers to some syntactic categories that
  14.197 -  are further defined in @{cite "isabelle-isar-ref"}.
  14.198 +  The syntax diagram below refers to some syntactic categories that are
  14.199 +  further defined in @{cite "isabelle-isar-ref"}.
  14.200  
  14.201    @{rail \<open>
  14.202      @@{method match} kind @'in' (pattern '\<Rightarrow>' cartouche + '\<bar>')
  14.203 @@ -296,10 +298,10 @@
  14.204    \<close>}
  14.205  
  14.206    Matching allows methods to introspect the goal state, and to implement more
  14.207 -  explicit control flow. In the basic case, a term or fact \<open>ts\<close> is given
  14.208 -  to match against as a \<^emph>\<open>match target\<close>, along with a collection of
  14.209 -  pattern-method pairs \<open>(p, m)\<close>: roughly speaking, when the pattern
  14.210 -  \<open>p\<close> matches any member of \<open>ts\<close>, the \<^emph>\<open>inner\<close> method \<open>m\<close> will be executed.
  14.211 +  explicit control flow. In the basic case, a term or fact \<open>ts\<close> is given to
  14.212 +  match against as a \<^emph>\<open>match target\<close>, along with a collection of
  14.213 +  pattern-method pairs \<open>(p, m)\<close>: roughly speaking, when the pattern \<open>p\<close>
  14.214 +  matches any member of \<open>ts\<close>, the \<^emph>\<open>inner\<close> method \<open>m\<close> will be executed.
  14.215  \<close>
  14.216  
  14.217      lemma
  14.218 @@ -310,11 +312,11 @@
  14.219          by (match X in I: "Q \<longrightarrow> P" and I': "Q" \<Rightarrow> \<open>insert mp [OF I I']\<close>)
  14.220  
  14.221  text \<open>
  14.222 -  In this example we have a structured Isar proof, with the named
  14.223 -  assumption \<open>X\<close> and a conclusion @{term "P"}. With the match method
  14.224 -  we can find the local facts @{term "Q \<longrightarrow> P"} and @{term "Q"}, binding them to
  14.225 -  separately as \<open>I\<close> and \<open>I'\<close>. We then specialize the
  14.226 -  modus-ponens rule @{thm mp [of Q P]} to these facts to solve the goal.
  14.227 +  In this example we have a structured Isar proof, with the named assumption
  14.228 +  \<open>X\<close> and a conclusion @{term "P"}. With the match method we can find the
  14.229 +  local facts @{term "Q \<longrightarrow> P"} and @{term "Q"}, binding them to separately as
  14.230 +  \<open>I\<close> and \<open>I'\<close>. We then specialize the modus-ponens rule @{thm mp [of Q P]} to
  14.231 +  these facts to solve the goal.
  14.232  \<close>
  14.233  
  14.234  
  14.235 @@ -324,15 +326,14 @@
  14.236    In the previous example we were able to match against an assumption out of
  14.237    the Isar proof state. In general, however, proof subgoals can be
  14.238    \<^emph>\<open>unstructured\<close>, with goal parameters and premises arising from rule
  14.239 -  application. To address this, @{method match} uses \<^emph>\<open>subgoal focusing\<close>
  14.240 -  to produce structured goals out of
  14.241 -  unstructured ones. In place of fact or term, we may give the
  14.242 -  keyword @{keyword_def "premises"} as the match target. This causes a subgoal
  14.243 -  focus on the first subgoal, lifting local goal parameters to fixed term
  14.244 -  variables and premises into hypothetical theorems. The match is performed
  14.245 -  against these theorems, naming them and binding them as appropriate.
  14.246 -  Similarly giving the keyword @{keyword_def "conclusion"} matches against the
  14.247 -  conclusion of the first subgoal.
  14.248 +  application. To address this, @{method match} uses \<^emph>\<open>subgoal focusing\<close> to
  14.249 +  produce structured goals out of unstructured ones. In place of fact or term,
  14.250 +  we may give the keyword @{keyword_def "premises"} as the match target. This
  14.251 +  causes a subgoal focus on the first subgoal, lifting local goal parameters
  14.252 +  to fixed term variables and premises into hypothetical theorems. The match
  14.253 +  is performed against these theorems, naming them and binding them as
  14.254 +  appropriate. Similarly giving the keyword @{keyword_def "conclusion"}
  14.255 +  matches against the conclusion of the first subgoal.
  14.256  
  14.257    An unstructured version of the previous example can then be similarly solved
  14.258    through focusing.
  14.259 @@ -358,16 +359,16 @@
  14.260    now-bound @{term A} (bound to @{term P}) against the conclusion (also @{term
  14.261    P}), finally applying the specialized rule to solve the goal.
  14.262  
  14.263 -  Schematic terms like \<open>?P\<close> may also be used to specify match
  14.264 -  variables, but the result of the match is not bound, and thus cannot be used
  14.265 -  in the inner method body.
  14.266 +  Schematic terms like \<open>?P\<close> may also be used to specify match variables, but
  14.267 +  the result of the match is not bound, and thus cannot be used in the inner
  14.268 +  method body.
  14.269  
  14.270    \<^medskip>
  14.271 -  In the following example we extract the predicate of an
  14.272 -  existentially quantified conclusion in the current subgoal and search the
  14.273 -  current premises for a matching fact. If both matches are successful, we
  14.274 -  then instantiate the existential introduction rule with both the witness and
  14.275 -  predicate, solving with the matched premise.
  14.276 +  In the following example we extract the predicate of an existentially
  14.277 +  quantified conclusion in the current subgoal and search the current premises
  14.278 +  for a matching fact. If both matches are successful, we then instantiate the
  14.279 +  existential introduction rule with both the witness and predicate, solving
  14.280 +  with the matched premise.
  14.281  \<close>
  14.282  
  14.283      method solve_ex =
  14.284 @@ -378,15 +379,14 @@
  14.285  text \<open>
  14.286    The first @{method match} matches the pattern @{term "\<exists>x. Q x"} against the
  14.287    current conclusion, binding the term @{term "Q"} in the inner match. Next
  14.288 -  the pattern \<open>Q y\<close> is matched against all premises of the current
  14.289 -  subgoal. In this case @{term "Q"} is fixed and @{term "y"} may be
  14.290 -  instantiated. Once a match is found, the local fact \<open>U\<close> is bound to
  14.291 -  the matching premise and the variable @{term "y"} is bound to the matching
  14.292 -  witness. The existential introduction rule \<open>exI:\<close>~@{thm exI} is then
  14.293 -  instantiated with @{term "y"} as the witness and @{term "Q"} as the
  14.294 -  predicate, with its proof obligation solved by the local fact U (using the
  14.295 -  Isar attribute @{attribute OF}). The following example is a trivial use of
  14.296 -  this method.
  14.297 +  the pattern \<open>Q y\<close> is matched against all premises of the current subgoal. In
  14.298 +  this case @{term "Q"} is fixed and @{term "y"} may be instantiated. Once a
  14.299 +  match is found, the local fact \<open>U\<close> is bound to the matching premise and the
  14.300 +  variable @{term "y"} is bound to the matching witness. The existential
  14.301 +  introduction rule \<open>exI:\<close>~@{thm exI} is then instantiated with @{term "y"} as
  14.302 +  the witness and @{term "Q"} as the predicate, with its proof obligation
  14.303 +  solved by the local fact U (using the Isar attribute @{attribute OF}). The
  14.304 +  following example is a trivial use of this method.
  14.305  \<close>
  14.306  
  14.307      lemma "halts p \<Longrightarrow> \<exists>x. halts x"
  14.308 @@ -419,13 +419,12 @@
  14.309    with a universal quantifier in the premises that matches the type of @{term
  14.310    y}. Since @{keyword "premises"} causes a focus, however, there are no
  14.311    subgoal premises to be found and thus @{method my_allE_bad} will always
  14.312 -  fail. If focusing instead left the premises in place, using methods
  14.313 -  like @{method erule} would lead to unintended behaviour, specifically during
  14.314 +  fail. If focusing instead left the premises in place, using methods like
  14.315 +  @{method erule} would lead to unintended behaviour, specifically during
  14.316    backtracking. In our example, @{method erule} could choose an alternate
  14.317 -  premise while backtracking, while leaving \<open>I\<close> bound to the original
  14.318 -  match. In the case of more complex inner methods, where either \<open>I\<close> or
  14.319 -  bound terms are used, this would almost certainly not be the intended
  14.320 -  behaviour.
  14.321 +  premise while backtracking, while leaving \<open>I\<close> bound to the original match.
  14.322 +  In the case of more complex inner methods, where either \<open>I\<close> or bound terms
  14.323 +  are used, this would almost certainly not be the intended behaviour.
  14.324  
  14.325    An alternative implementation would be to specialize the elimination rule to
  14.326    the bound term and apply it directly.
  14.327 @@ -444,13 +443,13 @@
  14.328    premise, it is not likely the intended behaviour. Repeated application of
  14.329    this method will produce an infinite stream of duplicate specialized
  14.330    premises, due to the original premise never being removed. To address this,
  14.331 -  matched premises may be declared with the @{attribute "thin"} attribute.
  14.332 -  This will hide the premise from subsequent inner matches, and remove it from
  14.333 -  the list of premises when the inner method has finished and the subgoal is
  14.334 +  matched premises may be declared with the @{attribute thin} attribute. This
  14.335 +  will hide the premise from subsequent inner matches, and remove it from the
  14.336 +  list of premises when the inner method has finished and the subgoal is
  14.337    unfocused. It can be considered analogous to the existing \<open>thin_tac\<close>.
  14.338  
  14.339 -  To complete our example, the correct implementation of the method
  14.340 -  will @{attribute "thin"} the premise from the match and then apply it to the
  14.341 +  To complete our example, the correct implementation of the method will
  14.342 +  @{attribute thin} the premise from the match and then apply it to the
  14.343    specialized elimination rule.\<close>
  14.344  
  14.345      method my_allE for y :: 'a =
  14.346 @@ -460,13 +459,14 @@
  14.347      lemma "\<forall>x. P x \<Longrightarrow> \<forall>x. Q x \<Longrightarrow> P y \<and> Q y"
  14.348        by (my_allE y)+ (rule conjI)
  14.349  
  14.350 +
  14.351  subsubsection \<open>Inner focusing\<close>
  14.352  
  14.353  text \<open>
  14.354 -  Premises are \<^emph>\<open>accumulated\<close> for the purposes of subgoal focusing.
  14.355 -  In contrast to using standard methods like @{method frule} within
  14.356 -  focused match, another @{method match} will have access to all the premises
  14.357 -  of the outer focus.
  14.358 +  Premises are \<^emph>\<open>accumulated\<close> for the purposes of subgoal focusing. In
  14.359 +  contrast to using standard methods like @{method frule} within focused
  14.360 +  match, another @{method match} will have access to all the premises of the
  14.361 +  outer focus.
  14.362  \<close>
  14.363  
  14.364      lemma "A \<Longrightarrow> B \<Longrightarrow> A \<and> B"
  14.365 @@ -475,25 +475,23 @@
  14.366  
  14.367  text \<open>
  14.368    In this example, the inner @{method match} can find the focused premise
  14.369 -  @{term B}. In contrast, the @{method assumption} method would fail here
  14.370 -  due to @{term B} not being logically accessible.
  14.371 +  @{term B}. In contrast, the @{method assumption} method would fail here due
  14.372 +  to @{term B} not being logically accessible.
  14.373  \<close>
  14.374  
  14.375 -    lemma
  14.376 -    "A \<Longrightarrow> A \<and> (B \<longrightarrow> B)"
  14.377 +    lemma "A \<Longrightarrow> A \<and> (B \<longrightarrow> B)"
  14.378        by (match premises in H: A \<Rightarrow> \<open>intro conjI, rule H, rule impI,
  14.379              match premises (local) in A \<Rightarrow> \<open>fail\<close>
  14.380                                   \<bar> H': B \<Rightarrow> \<open>rule H'\<close>\<close>)
  14.381  
  14.382  text \<open>
  14.383 -  In this example, the only premise that exists in the first focus is
  14.384 -  @{term "A"}. Prior to the inner match, the rule \<open>impI\<close> changes
  14.385 -  the goal @{term "B \<longrightarrow> B"} into @{term "B \<Longrightarrow> B"}. A standard premise
  14.386 -  match would also include @{term A} as an original premise of the outer
  14.387 -  match. The \<open>local\<close> argument limits the match to
  14.388 -  newly focused premises.
  14.389 +  In this example, the only premise that exists in the first focus is @{term
  14.390 +  "A"}. Prior to the inner match, the rule \<open>impI\<close> changes the goal @{term "B \<longrightarrow>
  14.391 +  B"} into @{term "B \<Longrightarrow> B"}. A standard premise match would also include @{term
  14.392 +  A} as an original premise of the outer match. The \<open>local\<close> argument limits
  14.393 +  the match to newly focused premises.
  14.394 +\<close>
  14.395  
  14.396 -\<close>
  14.397  
  14.398  section \<open>Attributes\<close>
  14.399  
  14.400 @@ -547,8 +545,7 @@
  14.401  text \<open>
  14.402    The @{attribute of} attribute behaves similarly. It is worth noting,
  14.403    however, that the positional instantiation of @{attribute of} occurs against
  14.404 -  the position of the variables as they are declared \<^emph>\<open>in the match
  14.405 -  pattern\<close>.
  14.406 +  the position of the variables as they are declared \<^emph>\<open>in the match pattern\<close>.
  14.407  \<close>
  14.408  
  14.409      lemma
  14.410 @@ -559,15 +556,16 @@
  14.411              \<open>rule I [of x y]\<close>)
  14.412  
  14.413  text \<open>
  14.414 -  In this example, the order of schematics in \<open>asm\<close> is actually \<open>?y ?x\<close>, but we instantiate our matched rule in the opposite order. This is
  14.415 -  because the effective rule @{term I} was bound from the match, which
  14.416 -  declared the @{typ 'a} slot first and the @{typ 'b} slot second.
  14.417 +  In this example, the order of schematics in \<open>asm\<close> is actually \<open>?y ?x\<close>, but
  14.418 +  we instantiate our matched rule in the opposite order. This is because the
  14.419 +  effective rule @{term I} was bound from the match, which declared the @{typ
  14.420 +  'a} slot first and the @{typ 'b} slot second.
  14.421  
  14.422    To get the dynamic behaviour of @{attribute of} we can choose to invoke it
  14.423 -  \<^emph>\<open>unchecked\<close>. This avoids trying to do any type inference for the
  14.424 -  provided parameters, instead storing them as their most general type and
  14.425 -  doing type matching at run-time. This, like @{attribute OF}, will throw
  14.426 -  errors if the expected slots don't exist or there is a type mismatch.
  14.427 +  \<^emph>\<open>unchecked\<close>. This avoids trying to do any type inference for the provided
  14.428 +  parameters, instead storing them as their most general type and doing type
  14.429 +  matching at run-time. This, like @{attribute OF}, will throw errors if the
  14.430 +  expected slots don't exist or there is a type mismatch.
  14.431  \<close>
  14.432  
  14.433      lemma
  14.434 @@ -587,11 +585,11 @@
  14.435              \<open>prop_solver\<close>)
  14.436  
  14.437  text \<open>
  14.438 -  In this example, the pattern \<open>\<And>x :: 'a. ?P x \<Longrightarrow> ?Q x\<close> matches against
  14.439 -  the only premise, giving an appropriately typed slot for @{term y}. After
  14.440 -  the match, the resulting rule is instantiated to @{term y} and then declared
  14.441 -  as an @{attribute intros} rule. This is then picked up by @{method
  14.442 -  prop_solver} to solve the goal.
  14.443 +  In this example, the pattern \<open>\<And>x :: 'a. ?P x \<Longrightarrow> ?Q x\<close> matches against the
  14.444 +  only premise, giving an appropriately typed slot for @{term y}. After the
  14.445 +  match, the resulting rule is instantiated to @{term y} and then declared as
  14.446 +  an @{attribute intros} rule. This is then picked up by @{method prop_solver}
  14.447 +  to solve the goal.
  14.448  \<close>
  14.449  
  14.450  
  14.451 @@ -600,8 +598,9 @@
  14.452  text \<open>
  14.453    In all previous examples, @{method match} was only ever searching for a
  14.454    single rule or premise. Each local fact would therefore always have a length
  14.455 -  of exactly one. We may, however, wish to find \<^emph>\<open>all\<close> matching results.
  14.456 -  To achieve this, we can simply mark a given pattern with the \<open>(multi)\<close> argument.
  14.457 +  of exactly one. We may, however, wish to find \<^emph>\<open>all\<close> matching results. To
  14.458 +  achieve this, we can simply mark a given pattern with the \<open>(multi)\<close>
  14.459 +  argument.
  14.460  \<close>
  14.461  
  14.462      lemma
  14.463 @@ -612,21 +611,21 @@
  14.464        done
  14.465  
  14.466  text \<open>
  14.467 -  In the first @{method match}, without the \<open>(multi)\<close> argument, @{term
  14.468 -  I} is only ever be bound to one of the members of \<open>asms\<close>. This
  14.469 -  backtracks over both possibilities (see next section), however neither
  14.470 -  assumption in isolation is sufficient to solve to goal. The use of the
  14.471 -  @{method solves} combinator ensures that @{method prop_solver} has no effect
  14.472 -  on the goal when it doesn't solve it, and so the first match leaves the goal
  14.473 -  unchanged. In the second @{method match}, \<open>I\<close> is bound to all of
  14.474 -  \<open>asms\<close>, declaring both results as \<open>intros\<close>. With these rules
  14.475 -  @{method prop_solver} is capable of solving the goal.
  14.476 +  In the first @{method match}, without the \<open>(multi)\<close> argument, @{term I} is
  14.477 +  only ever be bound to one of the members of \<open>asms\<close>. This backtracks over
  14.478 +  both possibilities (see next section), however neither assumption in
  14.479 +  isolation is sufficient to solve to goal. The use of the @{method solves}
  14.480 +  combinator ensures that @{method prop_solver} has no effect on the goal when
  14.481 +  it doesn't solve it, and so the first match leaves the goal unchanged. In
  14.482 +  the second @{method match}, \<open>I\<close> is bound to all of \<open>asms\<close>, declaring both
  14.483 +  results as \<open>intros\<close>. With these rules @{method prop_solver} is capable of
  14.484 +  solving the goal.
  14.485  
  14.486    Using for-fixed variables in patterns imposes additional constraints on the
  14.487 -  results. In all previous examples, the choice of using \<open>?P\<close> or a
  14.488 -  for-fixed @{term P} only depended on whether or not @{term P} was mentioned
  14.489 -  in another pattern or the inner method. When using a multi-match, however,
  14.490 -  all for-fixed terms must agree in the results.
  14.491 +  results. In all previous examples, the choice of using \<open>?P\<close> or a for-fixed
  14.492 +  @{term P} only depended on whether or not @{term P} was mentioned in another
  14.493 +  pattern or the inner method. When using a multi-match, however, all
  14.494 +  for-fixed terms must agree in the results.
  14.495  \<close>
  14.496  
  14.497      lemma
  14.498 @@ -641,11 +640,11 @@
  14.499  text \<open>
  14.500    Here we have two seemingly-equivalent applications of @{method match},
  14.501    however only the second one is capable of solving the goal. The first
  14.502 -  @{method match} selects the first and third members of \<open>asms\<close> (those
  14.503 -  that agree on their conclusion), which is not sufficient. The second
  14.504 -  @{method match} selects the first and second members of \<open>asms\<close> (those
  14.505 -  that agree on their assumption), which is enough for @{method prop_solver}
  14.506 -  to solve the goal.
  14.507 +  @{method match} selects the first and third members of \<open>asms\<close> (those that
  14.508 +  agree on their conclusion), which is not sufficient. The second @{method
  14.509 +  match} selects the first and second members of \<open>asms\<close> (those that agree on
  14.510 +  their assumption), which is enough for @{method prop_solver} to solve the
  14.511 +  goal.
  14.512  \<close>
  14.513  
  14.514  
  14.515 @@ -655,10 +654,10 @@
  14.516    Dummy patterns may be given as placeholders for unique schematics in
  14.517    patterns. They implicitly receive all currently bound variables as
  14.518    arguments, and are coerced into the @{typ prop} type whenever possible. For
  14.519 -  example, the trivial dummy pattern \<open>_\<close> will match any proposition.
  14.520 -  In contrast, by default the pattern \<open>?P\<close> is considered to have type
  14.521 -  @{typ bool}. It will not bind anything with meta-logical connectives (e.g.
  14.522 -  \<open>_ \<Longrightarrow> _\<close> or \<open>_ &&& _\<close>).
  14.523 +  example, the trivial dummy pattern \<open>_\<close> will match any proposition. In
  14.524 +  contrast, by default the pattern \<open>?P\<close> is considered to have type @{typ
  14.525 +  bool}. It will not bind anything with meta-logical connectives (e.g. \<open>_ \<Longrightarrow> _\<close>
  14.526 +  or \<open>_ &&& _\<close>).
  14.527  \<close>
  14.528  
  14.529      lemma
  14.530 @@ -670,19 +669,19 @@
  14.531  section \<open>Backtracking\<close>
  14.532  
  14.533  text \<open>
  14.534 -  Patterns are considered top-down, executing the inner method \<open>m\<close> of
  14.535 -  the first pattern which is satisfied by the current match target. By
  14.536 -  default, matching performs extensive backtracking by attempting all valid
  14.537 -  variable and fact bindings according to the given pattern. In particular,
  14.538 -  all unifiers for a given pattern will be explored, as well as each matching
  14.539 +  Patterns are considered top-down, executing the inner method \<open>m\<close> of the
  14.540 +  first pattern which is satisfied by the current match target. By default,
  14.541 +  matching performs extensive backtracking by attempting all valid variable
  14.542 +  and fact bindings according to the given pattern. In particular, all
  14.543 +  unifiers for a given pattern will be explored, as well as each matching
  14.544    fact. The inner method \<open>m\<close> will be re-executed for each different
  14.545    variable/fact binding during backtracking. A successful match is considered
  14.546    a cut-point for backtracking. Specifically, once a match is made no other
  14.547    pattern-method pairs will be considered.
  14.548  
  14.549 -  The method \<open>foo\<close> below fails for all goals that are conjunctions. Any
  14.550 -  such goal will match the first pattern, causing the second pattern (that
  14.551 -  would otherwise match all goals) to never be considered.
  14.552 +  The method \<open>foo\<close> below fails for all goals that are conjunctions. Any such
  14.553 +  goal will match the first pattern, causing the second pattern (that would
  14.554 +  otherwise match all goals) to never be considered.
  14.555  \<close>
  14.556  
  14.557      method foo =
  14.558 @@ -690,12 +689,12 @@
  14.559  
  14.560  text \<open>
  14.561    The failure of an inner method that is executed after a successful match
  14.562 -  will cause the entire match to fail. This distinction is important
  14.563 -  due to the pervasive use of backtracking. When a method is used in a
  14.564 -  combinator chain, its failure
  14.565 -  becomes significant because it signals previously applied methods to move to
  14.566 -  the next result. Therefore, it is necessary for @{method match} to not mask
  14.567 -  such failure. One can always rewrite a match using the combinators ``\<open>?\<close>'' and ``\<open>|\<close>'' to try subsequent patterns in the case of an
  14.568 +  will cause the entire match to fail. This distinction is important due to
  14.569 +  the pervasive use of backtracking. When a method is used in a combinator
  14.570 +  chain, its failure becomes significant because it signals previously applied
  14.571 +  methods to move to the next result. Therefore, it is necessary for @{method
  14.572 +  match} to not mask such failure. One can always rewrite a match using the
  14.573 +  combinators ``\<open>?\<close>'' and ``\<open>|\<close>'' to try subsequent patterns in the case of an
  14.574    inner-method failure. The following proof method, for example, always
  14.575    invokes @{method prop_solver} for all goals because its first alternative
  14.576    either never matches or (if it does match) always fails.
  14.577 @@ -710,8 +709,8 @@
  14.578  
  14.579  text \<open>
  14.580    Backtracking may be controlled more precisely by marking individual patterns
  14.581 -  as \<open>cut\<close>. This causes backtracking to not progress beyond this pattern:
  14.582 -  once a match is found no others will be considered.
  14.583 +  as \<open>cut\<close>. This causes backtracking to not progress beyond this pattern: once
  14.584 +  a match is found no others will be considered.
  14.585  \<close>
  14.586  
  14.587      method foo\<^sub>2 =
  14.588 @@ -722,10 +721,10 @@
  14.589    In this example, once a conjunction is found (@{term "P \<and> Q"}), all possible
  14.590    implications of @{term "P"} in the premises are considered, evaluating the
  14.591    inner @{method rule} with each consequent. No other conjunctions will be
  14.592 -  considered, with method failure occurring once all implications of the
  14.593 -  form \<open>P \<longrightarrow> ?U\<close> have been explored. Here the left-right processing of
  14.594 -  individual patterns is important, as all patterns after of the cut will
  14.595 -  maintain their usual backtracking behaviour.
  14.596 +  considered, with method failure occurring once all implications of the form
  14.597 +  \<open>P \<longrightarrow> ?U\<close> have been explored. Here the left-right processing of individual
  14.598 +  patterns is important, as all patterns after of the cut will maintain their
  14.599 +  usual backtracking behaviour.
  14.600  \<close>
  14.601  
  14.602      lemma "A \<and> B \<Longrightarrow> A \<longrightarrow> D \<Longrightarrow> A \<longrightarrow> C \<Longrightarrow> C"
  14.603 @@ -735,16 +734,16 @@
  14.604        by (foo\<^sub>2 | prop_solver)
  14.605  
  14.606  text \<open>
  14.607 -  In this example, the first lemma is solved by \<open>foo\<^sub>2\<close>, by first
  14.608 -  picking @{term "A \<longrightarrow> D"} for \<open>I'\<close>, then backtracking and ultimately
  14.609 -  succeeding after picking @{term "A \<longrightarrow> C"}. In the second lemma, however,
  14.610 -  @{term "C \<and> D"} is matched first, the second pattern in the match cannot be
  14.611 -  found and so the method fails, falling through to @{method prop_solver}.
  14.612 +  In this example, the first lemma is solved by \<open>foo\<^sub>2\<close>, by first picking
  14.613 +  @{term "A \<longrightarrow> D"} for \<open>I'\<close>, then backtracking and ultimately succeeding after
  14.614 +  picking @{term "A \<longrightarrow> C"}. In the second lemma, however, @{term "C \<and> D"} is
  14.615 +  matched first, the second pattern in the match cannot be found and so the
  14.616 +  method fails, falling through to @{method prop_solver}.
  14.617  
  14.618 -  More precise control is also possible by giving a positive
  14.619 -  number \<open>n\<close> as an argument to \<open>cut\<close>. This will limit the number
  14.620 -  of backtracking results of that match to be at most \<open>n\<close>.
  14.621 -  The match argument \<open>(cut 1)\<close> is the same as simply \<open>(cut)\<close>.
  14.622 +  More precise control is also possible by giving a positive number \<open>n\<close> as an
  14.623 +  argument to \<open>cut\<close>. This will limit the number of backtracking results of
  14.624 +  that match to be at most \<open>n\<close>. The match argument \<open>(cut 1)\<close> is the same as
  14.625 +  simply \<open>(cut)\<close>.
  14.626  \<close>
  14.627  
  14.628  
  14.629 @@ -769,15 +768,16 @@
  14.630  
  14.631  text \<open>
  14.632    Intuitively it seems like this proof should fail to check. The first match
  14.633 -  result, which binds @{term I} to the first two members of \<open>asms\<close>,
  14.634 -  fails the second inner match due to binding @{term P} to @{term A}.
  14.635 -  Backtracking then attempts to bind @{term I} to the third member of \<open>asms\<close>. This passes all inner matches, but fails when @{method rule} cannot
  14.636 -  successfully apply this to the current goal. After this, a valid match that
  14.637 -  is produced by the unifier is one which binds @{term P} to simply \<open>\<lambda>a. A ?x\<close>. The first inner match succeeds because \<open>\<lambda>a. A ?x\<close> does
  14.638 -  not match @{term A}. The next inner match succeeds because @{term I} has
  14.639 -  only been bound to the first member of \<open>asms\<close>. This is due to @{method
  14.640 -  match} considering \<open>\<lambda>a. A ?x\<close> and \<open>\<lambda>a. A ?y\<close> as distinct
  14.641 -  terms.
  14.642 +  result, which binds @{term I} to the first two members of \<open>asms\<close>, fails the
  14.643 +  second inner match due to binding @{term P} to @{term A}. Backtracking then
  14.644 +  attempts to bind @{term I} to the third member of \<open>asms\<close>. This passes all
  14.645 +  inner matches, but fails when @{method rule} cannot successfully apply this
  14.646 +  to the current goal. After this, a valid match that is produced by the
  14.647 +  unifier is one which binds @{term P} to simply \<open>\<lambda>a. A ?x\<close>. The first inner
  14.648 +  match succeeds because \<open>\<lambda>a. A ?x\<close> does not match @{term A}. The next inner
  14.649 +  match succeeds because @{term I} has only been bound to the first member of
  14.650 +  \<open>asms\<close>. This is due to @{method match} considering \<open>\<lambda>a. A ?x\<close> and \<open>\<lambda>a. A ?y\<close>
  14.651 +  as distinct terms.
  14.652  
  14.653    The simplest way to address this is to explicitly disallow term bindings
  14.654    which we would consider invalid.
  14.655 @@ -797,8 +797,8 @@
  14.656  text \<open>
  14.657    The @{method match} method is not aware of the logical content of match
  14.658    targets. Each pattern is simply matched against the shallow structure of a
  14.659 -  fact or term. Most facts are in \<^emph>\<open>normal form\<close>, which curries premises
  14.660 -  via meta-implication \<open>_ \<Longrightarrow> _\<close>.
  14.661 +  fact or term. Most facts are in \<^emph>\<open>normal form\<close>, which curries premises via
  14.662 +  meta-implication \<open>_ \<Longrightarrow> _\<close>.
  14.663  \<close>
  14.664  
  14.665      lemma
  14.666 @@ -821,17 +821,17 @@
  14.667  text \<open>
  14.668    This proof will fail to solve the goal. Our match pattern will only match
  14.669    rules which have a single premise, and conclusion @{term C}, so the first
  14.670 -  member of \<open>asms\<close> is not bound and thus the proof fails. Matching a
  14.671 -  pattern of the form @{term "P \<Longrightarrow> Q"} against this fact will bind @{term "P"}
  14.672 -  to @{term "A"} and @{term Q} to @{term "B \<Longrightarrow> C"}. Our pattern, with a
  14.673 -  concrete @{term "C"} in the conclusion, will fail to match this fact.
  14.674 +  member of \<open>asms\<close> is not bound and thus the proof fails. Matching a pattern
  14.675 +  of the form @{term "P \<Longrightarrow> Q"} against this fact will bind @{term "P"} to
  14.676 +  @{term "A"} and @{term Q} to @{term "B \<Longrightarrow> C"}. Our pattern, with a concrete
  14.677 +  @{term "C"} in the conclusion, will fail to match this fact.
  14.678  
  14.679 -  To express our desired match, we may \<^emph>\<open>uncurry\<close> our rules before
  14.680 -  matching against them. This forms a meta-conjunction of all premises in a
  14.681 -  fact, so that only one implication remains. For example the uncurried
  14.682 -  version of @{term "A \<Longrightarrow> B \<Longrightarrow> C"} is @{term "A &&& B \<Longrightarrow> C"}. This will now match
  14.683 -  our desired pattern \<open>_ \<Longrightarrow> C\<close>, and can be \<^emph>\<open>curried\<close> after the
  14.684 -  match to put it back into normal form.
  14.685 +  To express our desired match, we may \<^emph>\<open>uncurry\<close> our rules before matching
  14.686 +  against them. This forms a meta-conjunction of all premises in a fact, so
  14.687 +  that only one implication remains. For example the uncurried version of
  14.688 +  @{term "A \<Longrightarrow> B \<Longrightarrow> C"} is @{term "A &&& B \<Longrightarrow> C"}. This will now match our
  14.689 +  desired pattern \<open>_ \<Longrightarrow> C\<close>, and can be \<^emph>\<open>curried\<close> after the match to put it
  14.690 +  back into normal form.
  14.691  \<close>
  14.692  
  14.693      lemma
  14.694 @@ -858,12 +858,12 @@
  14.695        done
  14.696  
  14.697  text \<open>
  14.698 -  In the first @{method match} we attempt to find a member of \<open>asms\<close>
  14.699 -  which matches our goal precisely. This fails due to no such member existing.
  14.700 -  The second match reverses the role of the fact in the match, by first giving
  14.701 -  a general pattern @{term P}. This bound pattern is then matched against
  14.702 -  @{term "A y"}. In this case, @{term P} is bound to \<open>A ?x\<close> and so it
  14.703 -  successfully matches.
  14.704 +  In the first @{method match} we attempt to find a member of \<open>asms\<close> which
  14.705 +  matches our goal precisely. This fails due to no such member existing. The
  14.706 +  second match reverses the role of the fact in the match, by first giving a
  14.707 +  general pattern @{term P}. This bound pattern is then matched against @{term
  14.708 +  "A y"}. In this case, @{term P} is bound to \<open>A ?x\<close> and so it successfully
  14.709 +  matches.
  14.710  \<close>
  14.711  
  14.712  
  14.713 @@ -883,9 +883,10 @@
  14.714            \<open>match (y) in "y :: 'b" for y \<Rightarrow> \<open>rule H [where z = y]\<close>\<close>)
  14.715  
  14.716  text \<open>
  14.717 -  In this example the type \<open>'b\<close> is matched to \<open>'a\<close>, however
  14.718 -  statically they are formally distinct types. The first match binds \<open>'b\<close> while the inner match serves to coerce @{term y} into having the type
  14.719 -  \<open>'b\<close>. This allows the rule instantiation to successfully apply.
  14.720 +  In this example the type \<open>'b\<close> is matched to \<open>'a\<close>, however statically they
  14.721 +  are formally distinct types. The first match binds \<open>'b\<close> while the inner
  14.722 +  match serves to coerce @{term y} into having the type \<open>'b\<close>. This allows the
  14.723 +  rule instantiation to successfully apply.
  14.724  \<close>
  14.725  
  14.726  
  14.727 @@ -922,10 +923,10 @@
  14.728  
  14.729  text \<open>
  14.730    A custom rule attribute is a simple way to extend the functionality of
  14.731 -  Eisbach methods. The dummy rule attribute notation (\<open>[[ _ ]]\<close>)
  14.732 -  invokes the given attribute against a dummy fact and evaluates to the result
  14.733 -  of that attribute. When used as a match target, this can serve as an
  14.734 -  effective auxiliary function.
  14.735 +  Eisbach methods. The dummy rule attribute notation (\<open>[[ _ ]]\<close>) invokes the
  14.736 +  given attribute against a dummy fact and evaluates to the result of that
  14.737 +  attribute. When used as a match target, this can serve as an effective
  14.738 +  auxiliary function.
  14.739  \<close>
  14.740  
  14.741      attribute_setup get_split_rule =
    15.1 --- a/src/Doc/Eisbach/Preface.thy	Tue Nov 10 14:18:41 2015 +0000
    15.2 +++ b/src/Doc/Eisbach/Preface.thy	Tue Nov 10 14:43:29 2015 +0000
    15.3 @@ -5,10 +5,10 @@
    15.4  begin
    15.5  
    15.6  text \<open>
    15.7 -  \<^emph>\<open>Eisbach\<close> is a collection of tools which form the basis for defining
    15.8 -  new proof methods in Isabelle/Isar~@{cite "Wenzel-PhD"}. It can be thought
    15.9 -  of as a ``proof method language'', but is more precisely an infrastructure
   15.10 -  for defining new proof methods out of existing ones.
   15.11 +  \<^emph>\<open>Eisbach\<close> is a collection of tools which form the basis for defining new
   15.12 +  proof methods in Isabelle/Isar~@{cite "Wenzel-PhD"}. It can be thought of as
   15.13 +  a ``proof method language'', but is more precisely an infrastructure for
   15.14 +  defining new proof methods out of existing ones.
   15.15  
   15.16    The core functionality of Eisbach is provided by the Isar @{command method}
   15.17    command. Here users may define new methods by combining existing ones with
   15.18 @@ -27,8 +27,8 @@
   15.19    high barrier-to-entry for many users.
   15.20  
   15.21    \<^medskip>
   15.22 -  This manual is written for users familiar with Isabelle/Isar, but
   15.23 -  not necessarily Isabelle/ML. It covers the usage of the @{command method} as
   15.24 +  This manual is written for users familiar with Isabelle/Isar, but not
   15.25 +  necessarily Isabelle/ML. It covers the usage of the @{command method} as
   15.26    well as the @{method match} method, as well as discussing their integration
   15.27    with existing Isar concepts such as @{command named_theorems}.
   15.28  \<close>
    16.1 --- a/src/Doc/Implementation/Isar.thy	Tue Nov 10 14:18:41 2015 +0000
    16.2 +++ b/src/Doc/Implementation/Isar.thy	Tue Nov 10 14:43:29 2015 +0000
    16.3 @@ -183,10 +183,10 @@
    16.4    method space, e.g.\ @{method rule_tac}.
    16.5  
    16.6    \<^item> A non-trivial method always needs to make progress: an
    16.7 -  identical follow-up goal state has to be avoided.\footnote{This
    16.8 +  identical follow-up goal state has to be avoided.\<^footnote>\<open>This
    16.9    enables the user to write method expressions like \<open>meth\<^sup>+\<close>
   16.10    without looping, while the trivial do-nothing case can be recovered
   16.11 -  via \<open>meth\<^sup>?\<close>.}
   16.12 +  via \<open>meth\<^sup>?\<close>.\<close>
   16.13  
   16.14    Exception: trivial stuttering steps, such as ``@{method -}'' or
   16.15    @{method succeed}.
   16.16 @@ -275,11 +275,11 @@
   16.17    When implementing proof methods, it is advisable to study existing
   16.18    implementations carefully and imitate the typical ``boiler plate''
   16.19    for context-sensitive parsing and further combinators to wrap-up
   16.20 -  tactic expressions as methods.\footnote{Aliases or abbreviations of
   16.21 +  tactic expressions as methods.\<^footnote>\<open>Aliases or abbreviations of
   16.22    the standard method combinators should be avoided.  Note that from
   16.23    Isabelle99 until Isabelle2009 the system did provide various odd
   16.24    combinations of method syntax wrappers that made applications more
   16.25 -  complicated than necessary.}
   16.26 +  complicated than necessary.\<close>
   16.27  \<close>
   16.28  
   16.29  text %mlref \<open>
    17.1 --- a/src/Doc/Implementation/Logic.thy	Tue Nov 10 14:18:41 2015 +0000
    17.2 +++ b/src/Doc/Implementation/Logic.thy	Tue Nov 10 14:43:29 2015 +0000
    17.3 @@ -19,11 +19,11 @@
    17.4    Derivations are relative to a logical theory, which declares type
    17.5    constructors, constants, and axioms.  Theory declarations support
    17.6    schematic polymorphism, which is strictly speaking outside the
    17.7 -  logic.\footnote{This is the deeper logical reason, why the theory
    17.8 +  logic.\<^footnote>\<open>This is the deeper logical reason, why the theory
    17.9    context \<open>\<Theta>\<close> is separate from the proof context \<open>\<Gamma>\<close>
   17.10    of the core calculus: type constructors, term constants, and facts
   17.11    (proof constants) may involve arbitrary type schemes, but the type
   17.12 -  of a locally fixed term parameter is also fixed!}
   17.13 +  of a locally fixed term parameter is also fixed!\<close>
   17.14  \<close>
   17.15  
   17.16  
   17.17 @@ -531,9 +531,9 @@
   17.18    the simple syntactic types of Pure are always inhabitable.
   17.19    ``Assumptions'' \<open>x :: \<tau>\<close> for type-membership are only
   17.20    present as long as some \<open>x\<^sub>\<tau>\<close> occurs in the statement
   17.21 -  body.\footnote{This is the key difference to ``\<open>\<lambda>HOL\<close>'' in
   17.22 +  body.\<^footnote>\<open>This is the key difference to ``\<open>\<lambda>HOL\<close>'' in
   17.23    the PTS framework @{cite "Barendregt-Geuvers:2001"}, where hypotheses
   17.24 -  \<open>x : A\<close> are treated uniformly for propositions and types.}
   17.25 +  \<open>x : A\<close> are treated uniformly for propositions and types.\<close>
   17.26  
   17.27    \<^medskip>
   17.28    The axiomatization of a theory is implicitly closed by
    18.1 --- a/src/Doc/Implementation/ML.thy	Tue Nov 10 14:18:41 2015 +0000
    18.2 +++ b/src/Doc/Implementation/ML.thy	Tue Nov 10 14:43:29 2015 +0000
    18.3 @@ -23,11 +23,11 @@
    18.4    first-hand explanations should help to understand how proper
    18.5    Isabelle/ML is to be read and written, and to get access to the
    18.6    wealth of experience that is expressed in the source text and its
    18.7 -  history of changes.\footnote{See
    18.8 +  history of changes.\<^footnote>\<open>See
    18.9    @{url "http://isabelle.in.tum.de/repos/isabelle"} for the full
   18.10    Mercurial history.  There are symbolic tags to refer to official
   18.11    Isabelle releases, as opposed to arbitrary \<^emph>\<open>tip\<close> versions that
   18.12 -  merely reflect snapshots that are never really up-to-date.}\<close>
   18.13 +  merely reflect snapshots that are never really up-to-date.\<close>\<close>
   18.14  
   18.15  
   18.16  section \<open>Style and orthography\<close>
   18.17 @@ -37,10 +37,10 @@
   18.18    to tell an informed reader what is really going on and how things
   18.19    really work.  This is a non-trivial aim, but it is supported by a
   18.20    certain style of writing Isabelle/ML that has emerged from long
   18.21 -  years of system development.\footnote{See also the interesting style
   18.22 +  years of system development.\<^footnote>\<open>See also the interesting style
   18.23    guide for OCaml
   18.24    @{url "http://caml.inria.fr/resources/doc/guides/guidelines.en.html"}
   18.25 -  which shares many of our means and ends.}
   18.26 +  which shares many of our means and ends.\<close>
   18.27  
   18.28    The main principle behind any coding style is \<^emph>\<open>consistency\<close>.
   18.29    For a single author of a small program this merely means ``choose
   18.30 @@ -123,10 +123,10 @@
   18.31    For historical reasons, many capitalized names omit underscores,
   18.32    e.g.\ old-style @{ML_text FooBar} instead of @{ML_text Foo_Bar}.
   18.33    Genuine mixed-case names are \<^emph>\<open>not\<close> used, because clear division
   18.34 -  of words is essential for readability.\footnote{Camel-case was
   18.35 +  of words is essential for readability.\<^footnote>\<open>Camel-case was
   18.36    invented to workaround the lack of underscore in some early
   18.37    non-ASCII character sets.  Later it became habitual in some language
   18.38 -  communities that are now strong in numbers.}
   18.39 +  communities that are now strong in numbers.\<close>
   18.40  
   18.41    A single (capital) character does not count as ``word'' in this
   18.42    respect: some Isabelle/ML names are suffixed by extra markers like
   18.43 @@ -279,10 +279,10 @@
   18.44  
   18.45  paragraph \<open>Line length\<close>
   18.46  text \<open>is limited to 80 characters according to ancient standards, but we allow
   18.47 -  as much as 100 characters (not more).\footnote{Readability requires to keep
   18.48 +  as much as 100 characters (not more).\<^footnote>\<open>Readability requires to keep
   18.49    the beginning of a line in view while watching its end. Modern wide-screen
   18.50    displays do not change the way how the human brain works. Sources also need
   18.51 -  to be printable on plain paper with reasonable font-size.} The extra 20
   18.52 +  to be printable on plain paper with reasonable font-size.\<close> The extra 20
   18.53    characters acknowledge the space requirements due to qualified library
   18.54    references in Isabelle/ML.\<close>
   18.55  
   18.56 @@ -327,11 +327,11 @@
   18.57  \<close>
   18.58  
   18.59  paragraph \<open>Indentation\<close>
   18.60 -text \<open>uses plain spaces, never hard tabulators.\footnote{Tabulators were
   18.61 +text \<open>uses plain spaces, never hard tabulators.\<^footnote>\<open>Tabulators were
   18.62    invented to move the carriage of a type-writer to certain predefined
   18.63    positions. In software they could be used as a primitive run-length
   18.64    compression of consecutive spaces, but the precise result would depend on
   18.65 -  non-standardized text editor configuration.}
   18.66 +  non-standardized text editor configuration.\<close>
   18.67  
   18.68    Each level of nesting is indented by 2 spaces, sometimes 1, very
   18.69    rarely 4, never 8 or any other odd number.
   18.70 @@ -562,10 +562,10 @@
   18.71    Removing the above ML declaration from the source text will remove any trace
   18.72    of this definition, as expected. The Isabelle/ML toplevel environment is
   18.73    managed in a \<^emph>\<open>stateless\<close> way: in contrast to the raw ML toplevel, there
   18.74 -  are no global side-effects involved here.\footnote{Such a stateless
   18.75 +  are no global side-effects involved here.\<^footnote>\<open>Such a stateless
   18.76    compilation environment is also a prerequisite for robust parallel
   18.77    compilation within independent nodes of the implicit theory development
   18.78 -  graph.}
   18.79 +  graph.\<close>
   18.80  
   18.81    \<^medskip>
   18.82    The next example shows how to embed ML into Isar proofs, using
   18.83 @@ -578,7 +578,7 @@
   18.84    ML_prf %"ML" \<open>val a = 1\<close>
   18.85    {
   18.86      ML_prf %"ML" \<open>val b = a + 1\<close>
   18.87 -  } -- \<open>Isar block structure ignored by ML environment\<close>
   18.88 +  } \<comment> \<open>Isar block structure ignored by ML environment\<close>
   18.89    ML_prf %"ML" \<open>val c = b + 1\<close>
   18.90  end
   18.91  
   18.92 @@ -739,9 +739,9 @@
   18.93    type \<open>\<tau>\<close> is represented by the iterated function space
   18.94    \<open>\<tau>\<^sub>1 \<rightarrow> \<dots> \<rightarrow> \<tau>\<^sub>n \<rightarrow> \<tau>\<close>.  This is isomorphic to the well-known
   18.95    encoding via tuples \<open>\<tau>\<^sub>1 \<times> \<dots> \<times> \<tau>\<^sub>n \<rightarrow> \<tau>\<close>, but the curried
   18.96 -  version fits more smoothly into the basic calculus.\footnote{The
   18.97 +  version fits more smoothly into the basic calculus.\<^footnote>\<open>The
   18.98    difference is even more significant in HOL, because the redundant
   18.99 -  tuple structure needs to be accommodated extraneous proof steps.}
  18.100 +  tuple structure needs to be accommodated extraneous proof steps.\<close>
  18.101  
  18.102    Currying gives some flexibility due to \<^emph>\<open>partial application\<close>.  A
  18.103    function \<open>f: \<tau>\<^sub>1 \<rightarrow> \<tau>\<^sub>2 \<rightarrow> \<tau>\<close> can be applied to \<open>x: \<tau>\<^sub>1\<close>
  18.104 @@ -1282,9 +1282,9 @@
  18.105    \<^descr> @{ML "Symbol.explode"}~\<open>str\<close> produces a symbol list
  18.106    from the packed form.  This function supersedes @{ML
  18.107    "String.explode"} for virtually all purposes of manipulating text in
  18.108 -  Isabelle!\footnote{The runtime overhead for exploded strings is
  18.109 +  Isabelle!\<^footnote>\<open>The runtime overhead for exploded strings is
  18.110    mainly that of the list structure: individual symbols that happen to
  18.111 -  be a singleton string do not require extra memory in Poly/ML.}
  18.112 +  be a singleton string do not require extra memory in Poly/ML.\<close>
  18.113  
  18.114    \<^descr> @{ML "Symbol.is_letter"}, @{ML "Symbol.is_digit"}, @{ML
  18.115    "Symbol.is_quasi"}, @{ML "Symbol.is_blank"} classify standard
  18.116 @@ -1396,8 +1396,8 @@
  18.117  
  18.118    \<^descr> Type @{ML_type int} represents regular mathematical integers, which
  18.119    are \<^emph>\<open>unbounded\<close>. Overflow is treated properly, but should never happen
  18.120 -  in practice.\footnote{The size limit for integer bit patterns in memory is
  18.121 -  64\,MB for 32-bit Poly/ML, and much higher for 64-bit systems.} This works
  18.122 +  in practice.\<^footnote>\<open>The size limit for integer bit patterns in memory is
  18.123 +  64\,MB for 32-bit Poly/ML, and much higher for 64-bit systems.\<close> This works
  18.124    uniformly for all supported ML platforms (Poly/ML and SML/NJ).
  18.125  
  18.126    Literal integers in ML text are forced to be of this one true
  18.127 @@ -1614,13 +1614,13 @@
  18.128    sub-components with explicit communication, general asynchronous
  18.129    interaction etc.  Moreover, parallel evaluation is a prerequisite to
  18.130    make adequate use of the CPU resources that are available on
  18.131 -  multi-core systems.\footnote{Multi-core computing does not mean that
  18.132 +  multi-core systems.\<^footnote>\<open>Multi-core computing does not mean that
  18.133    there are ``spare cycles'' to be wasted.  It means that the
  18.134    continued exponential speedup of CPU performance due to ``Moore's
  18.135    Law'' follows different rules: clock frequency has reached its peak
  18.136    around 2005, and applications need to be parallelized in order to
  18.137    avoid a perceived loss of performance.  See also
  18.138 -  @{cite "Sutter:2005"}.}
  18.139 +  @{cite "Sutter:2005"}.\<close>
  18.140  
  18.141    Isabelle/Isar exploits the inherent structure of theories and proofs to
  18.142    support \<^emph>\<open>implicit parallelism\<close> to a large extent. LCF-style theorem
  18.143 @@ -1671,8 +1671,8 @@
  18.144  
  18.145    \<^item> Global references (or arrays), i.e.\ mutable memory cells that
  18.146    persist over several invocations of associated
  18.147 -  operations.\footnote{This is independent of the visibility of such
  18.148 -  mutable values in the toplevel scope.}
  18.149 +  operations.\<^footnote>\<open>This is independent of the visibility of such
  18.150 +  mutable values in the toplevel scope.\<close>
  18.151  
  18.152    \<^item> Global state of the running Isabelle/ML process, i.e.\ raw I/O
  18.153    channels, environment variables, current working directory.
    19.1 --- a/src/Doc/Implementation/Prelim.thy	Tue Nov 10 14:18:41 2015 +0000
    19.2 +++ b/src/Doc/Implementation/Prelim.thy	Tue Nov 10 14:43:29 2015 +0000
    19.3 @@ -471,17 +471,17 @@
    19.4  begin
    19.5  
    19.6  declare [[show_types = false]]
    19.7 -  -- \<open>declaration within (local) theory context\<close>
    19.8 +  \<comment> \<open>declaration within (local) theory context\<close>
    19.9  
   19.10  notepad
   19.11  begin
   19.12    note [[show_types = true]]
   19.13 -    -- \<open>declaration within proof (forward mode)\<close>
   19.14 +    \<comment> \<open>declaration within proof (forward mode)\<close>
   19.15    term x
   19.16  
   19.17    have "x = x"
   19.18      using [[show_types = false]]
   19.19 -      -- \<open>declaration within proof (backward mode)\<close>
   19.20 +      \<comment> \<open>declaration within proof (backward mode)\<close>
   19.21      ..
   19.22  end
   19.23  
    20.1 --- a/src/Doc/Implementation/Proof.thy	Tue Nov 10 14:18:41 2015 +0000
    20.2 +++ b/src/Doc/Implementation/Proof.thy	Tue Nov 10 14:43:29 2015 +0000
    20.3 @@ -58,14 +58,14 @@
    20.4  notepad
    20.5  begin
    20.6    {
    20.7 -    fix x  -- \<open>all potential occurrences of some \<open>x::\<tau>\<close> are fixed\<close>
    20.8 +    fix x  \<comment> \<open>all potential occurrences of some \<open>x::\<tau>\<close> are fixed\<close>
    20.9      {
   20.10 -      have "x::'a \<equiv> x"  -- \<open>implicit type assignment by concrete occurrence\<close>
   20.11 +      have "x::'a \<equiv> x"  \<comment> \<open>implicit type assignment by concrete occurrence\<close>
   20.12          by (rule reflexive)
   20.13      }
   20.14 -    thm this  -- \<open>result still with fixed type \<open>'a\<close>\<close>
   20.15 +    thm this  \<comment> \<open>result still with fixed type \<open>'a\<close>\<close>
   20.16    }
   20.17 -  thm this  -- \<open>fully general result for arbitrary \<open>?x::?'a\<close>\<close>
   20.18 +  thm this  \<comment> \<open>fully general result for arbitrary \<open>?x::?'a\<close>\<close>
   20.19  end
   20.20  
   20.21  text \<open>The Isabelle/Isar proof context manages the details of term
    21.1 --- a/src/Doc/Implementation/Syntax.thy	Tue Nov 10 14:18:41 2015 +0000
    21.2 +++ b/src/Doc/Implementation/Syntax.thy	Tue Nov 10 14:43:29 2015 +0000
    21.3 @@ -20,9 +20,9 @@
    21.4    Moreover, type-inference in the style of Hindley-Milner @{cite hindleymilner}
    21.5    (and extensions) enables users to write \<open>\<forall>x. B x\<close> concisely, when
    21.6    the type \<open>'a\<close> is already clear from the
    21.7 -  context.\footnote{Type-inference taken to the extreme can easily confuse
    21.8 +  context.\<^footnote>\<open>Type-inference taken to the extreme can easily confuse
    21.9    users. Beginners often stumble over unexpectedly general types inferred by
   21.10 -  the system.}
   21.11 +  the system.\<close>
   21.12  
   21.13    \<^medskip>
   21.14    The main inner syntax operations are \<^emph>\<open>read\<close> for
    22.1 --- a/src/Doc/Implementation/Tactic.thy	Tue Nov 10 14:18:41 2015 +0000
    22.2 +++ b/src/Doc/Implementation/Tactic.thy	Tue Nov 10 14:43:29 2015 +0000
    22.3 @@ -18,10 +18,10 @@
    22.4    Isabelle/Pure represents a goal as a theorem stating that the
    22.5    subgoals imply the main goal: \<open>A\<^sub>1 \<Longrightarrow> \<dots> \<Longrightarrow> A\<^sub>n \<Longrightarrow>
    22.6    C\<close>.  The outermost goal structure is that of a Horn Clause: i.e.\
    22.7 -  an iterated implication without any quantifiers\footnote{Recall that
    22.8 +  an iterated implication without any quantifiers\<^footnote>\<open>Recall that
    22.9    outermost \<open>\<And>x. \<phi>[x]\<close> is always represented via schematic
   22.10    variables in the body: \<open>\<phi>[?x]\<close>.  These variables may get
   22.11 -  instantiated during the course of reasoning.}.  For \<open>n = 0\<close>
   22.12 +  instantiated during the course of reasoning.\<close>.  For \<open>n = 0\<close>
   22.13    a goal is called ``solved''.
   22.14  
   22.15    The structure of each subgoal \<open>A\<^sub>i\<close> is that of a
   22.16 @@ -90,11 +90,11 @@
   22.17    \secref{sec:tactical-goals}) to a lazy sequence of potential
   22.18    successor states.  The underlying sequence implementation is lazy
   22.19    both in head and tail, and is purely functional in \<^emph>\<open>not\<close>
   22.20 -  supporting memoing.\footnote{The lack of memoing and the strict
   22.21 +  supporting memoing.\<^footnote>\<open>The lack of memoing and the strict
   22.22    nature of ML requires some care when working with low-level
   22.23    sequence operations, to avoid duplicate or premature evaluation of
   22.24    results.  It also means that modified runtime behavior, such as
   22.25 -  timeout, is very hard to achieve for general tactics.}
   22.26 +  timeout, is very hard to achieve for general tactics.\<close>
   22.27  
   22.28    An \<^emph>\<open>empty result sequence\<close> means that the tactic has failed: in
   22.29    a compound tactic expression other tactics might be tried instead,
   22.30 @@ -319,12 +319,12 @@
   22.31    \<^descr> @{ML match_tac}, @{ML ematch_tac}, @{ML dmatch_tac}, and @{ML
   22.32    bimatch_tac} are similar to @{ML resolve_tac}, @{ML eresolve_tac},
   22.33    @{ML dresolve_tac}, and @{ML biresolve_tac}, respectively, but do
   22.34 -  not instantiate schematic variables in the goal state.%
   22.35 -\footnote{Strictly speaking, matching means to treat the unknowns in the goal
   22.36 +  not instantiate schematic variables in the goal state.\<^footnote>\<open>Strictly speaking,
   22.37 +  matching means to treat the unknowns in the goal
   22.38    state as constants, but these tactics merely discard unifiers that would
   22.39    update the goal state. In rare situations (where the conclusion and 
   22.40    goal state have flexible terms at the same position), the tactic
   22.41 -  will fail even though an acceptable unifier exists.}
   22.42 +  will fail even though an acceptable unifier exists.\<close>
   22.43    These tactics were written for a specific application within the classical reasoner.
   22.44  
   22.45    Flexible subgoals are not updated at will, but are left alone.
    23.1 --- a/src/Doc/Isar_Ref/Document_Preparation.thy	Tue Nov 10 14:18:41 2015 +0000
    23.2 +++ b/src/Doc/Isar_Ref/Document_Preparation.thy	Tue Nov 10 14:43:29 2015 +0000
    23.3 @@ -134,13 +134,16 @@
    23.4    surrounding \<^verbatim>\<open>@{\<close>\<open>\<dots>\<close>\<^verbatim>\<open>}\<close>) works for a single
    23.5    argument that is a cartouche.
    23.6  
    23.7 -  Omitting the control symbol is also possible: a cartouche without special
    23.8 -  decoration is equivalent to \<^verbatim>\<open>\<^cartouche>\<close>\<open>\<open>argument_content\<close>\<close>, which
    23.9 -  is equivalent to \<^verbatim>\<open>@{cartouche\<close>~\<open>\<open>argument_content\<close>\<close>\<^verbatim>\<open>}\<close>. The
   23.10 -  special name @{antiquotation_def cartouche} is defined in the context:
   23.11 -  Isabelle/Pure introduces that as an alias to @{antiquotation_ref text}
   23.12 -  (see below). Consequently, \<open>\<open>foo_bar + baz \<le> bazar\<close>\<close> prints literal
   23.13 -  quasi-formal text (unchecked).
   23.14 +  A cartouche without special decoration is equivalent to
   23.15 +  \<^verbatim>\<open>\<^cartouche>\<close>\<open>\<open>argument_content\<close>\<close>, which is equivalent to
   23.16 +  \<^verbatim>\<open>@{cartouche\<close>~\<open>\<open>argument_content\<close>\<close>\<^verbatim>\<open>}\<close>. The special name
   23.17 +  @{antiquotation_def cartouche} is defined in the context: Isabelle/Pure
   23.18 +  introduces that as an alias to @{antiquotation_ref text} (see below).
   23.19 +  Consequently, \<open>\<open>foo_bar + baz \<le> bazar\<close>\<close> prints literal quasi-formal text
   23.20 +  (unchecked).
   23.21 +
   23.22 +  A control symbol \<^verbatim>\<open>\\<close>\<^verbatim>\<open><^\<close>\<open>name\<close>\<^verbatim>\<open>>\<close> within the body text, but without a
   23.23 +  subsequent cartouche, is equivalent to \<^verbatim>\<open>@{\<close>\<open>name\<close>\<^verbatim>\<open>}\<close>.
   23.24  
   23.25    \begingroup
   23.26    \def\isasymcontrolstart{\isatt{\isacharbackslash\isacharless\isacharcircum}}
    24.1 --- a/src/Doc/Isar_Ref/First_Order_Logic.thy	Tue Nov 10 14:18:41 2015 +0000
    24.2 +++ b/src/Doc/Isar_Ref/First_Order_Logic.thy	Tue Nov 10 14:43:29 2015 +0000
    24.3 @@ -357,10 +357,10 @@
    24.4  theorem
    24.5    assumes "\<exists>x. \<forall>y. R x y"
    24.6    shows "\<forall>y. \<exists>x. R x y"
    24.7 -proof    -- \<open>\<open>\<forall>\<close> introduction\<close>
    24.8 -  obtain x where "\<forall>y. R x y" using \<open>\<exists>x. \<forall>y. R x y\<close> ..    -- \<open>\<open>\<exists>\<close> elimination\<close>
    24.9 -  fix y have "R x y" using \<open>\<forall>y. R x y\<close> ..    -- \<open>\<open>\<forall>\<close> destruction\<close>
   24.10 -  then show "\<exists>x. R x y" ..    -- \<open>\<open>\<exists>\<close> introduction\<close>
   24.11 +proof    \<comment> \<open>\<open>\<forall>\<close> introduction\<close>
   24.12 +  obtain x where "\<forall>y. R x y" using \<open>\<exists>x. \<forall>y. R x y\<close> ..    \<comment> \<open>\<open>\<exists>\<close> elimination\<close>
   24.13 +  fix y have "R x y" using \<open>\<forall>y. R x y\<close> ..    \<comment> \<open>\<open>\<forall>\<close> destruction\<close>
   24.14 +  then show "\<exists>x. R x y" ..    \<comment> \<open>\<open>\<exists>\<close> introduction\<close>
   24.15  qed
   24.16  
   24.17  
    25.1 --- a/src/Doc/Isar_Ref/Generic.thy	Tue Nov 10 14:18:41 2015 +0000
    25.2 +++ b/src/Doc/Isar_Ref/Generic.thy	Tue Nov 10 14:43:29 2015 +0000
    25.3 @@ -327,9 +327,9 @@
    25.4  
    25.5    \<^descr> @{method simp_all} is similar to @{method simp}, but acts on
    25.6    all goals, working backwards from the last to the first one as usual
    25.7 -  in Isabelle.\footnote{The order is irrelevant for goals without
    25.8 +  in Isabelle.\<^footnote>\<open>The order is irrelevant for goals without
    25.9    schematic variables, so simplification might actually be performed
   25.10 -  in parallel here.}
   25.11 +  in parallel here.\<close>
   25.12  
   25.13    Chained facts are inserted into all subgoals, before the
   25.14    simplification process starts.  Further rule declarations are the
   25.15 @@ -347,8 +347,8 @@
   25.16    normalization process, or simplifying assumptions themselves.
   25.17    Further options allow to fine-tune the behavior of the Simplifier
   25.18    in this respect, corresponding to a variety of ML tactics as
   25.19 -  follows.\footnote{Unlike the corresponding Isar proof methods, the
   25.20 -  ML tactics do not insist in changing the goal state.}
   25.21 +  follows.\<^footnote>\<open>Unlike the corresponding Isar proof methods, the
   25.22 +  ML tactics do not insist in changing the goal state.\<close>
   25.23  
   25.24    \begin{center}
   25.25    \small
   25.26 @@ -1179,9 +1179,9 @@
   25.27    is easier to automate.
   25.28  
   25.29    A \<^bold>\<open>sequent\<close> has the form \<open>\<Gamma> \<turnstile> \<Delta>\<close>, where \<open>\<Gamma>\<close>
   25.30 -  and \<open>\<Delta>\<close> are sets of formulae.\footnote{For first-order
   25.31 +  and \<open>\<Delta>\<close> are sets of formulae.\<^footnote>\<open>For first-order
   25.32    logic, sequents can equivalently be made from lists or multisets of
   25.33 -  formulae.} The sequent \<open>P\<^sub>1, \<dots>, P\<^sub>m \<turnstile> Q\<^sub>1, \<dots>, Q\<^sub>n\<close> is
   25.34 +  formulae.\<close> The sequent \<open>P\<^sub>1, \<dots>, P\<^sub>m \<turnstile> Q\<^sub>1, \<dots>, Q\<^sub>n\<close> is
   25.35    \<^bold>\<open>valid\<close> if \<open>P\<^sub>1 \<and> \<dots> \<and> P\<^sub>m\<close> implies \<open>Q\<^sub>1 \<or> \<dots> \<or>
   25.36    Q\<^sub>n\<close>.  Thus \<open>P\<^sub>1, \<dots>, P\<^sub>m\<close> represent assumptions, each of which
   25.37    is true, while \<open>Q\<^sub>1, \<dots>, Q\<^sub>n\<close> represent alternative goals.  A
    26.1 --- a/src/Doc/Isar_Ref/Inner_Syntax.thy	Tue Nov 10 14:18:41 2015 +0000
    26.2 +++ b/src/Doc/Isar_Ref/Inner_Syntax.thy	Tue Nov 10 14:43:29 2015 +0000
    26.3 @@ -277,8 +277,8 @@
    26.4    used internally in Isabelle/Pure.
    26.5  
    26.6    \<^item> \<^verbatim>\<open>xsymbols\<close>: enable proper mathematical symbols
    26.7 -  instead of ASCII art.\footnote{This traditional mode name stems from
    26.8 -  the ``X-Symbol'' package for classic Proof~General with XEmacs.}
    26.9 +  instead of ASCII art.\<^footnote>\<open>This traditional mode name stems from
   26.10 +  the ``X-Symbol'' package for classic Proof~General with XEmacs.\<close>
   26.11  
   26.12    \<^item> \<^verbatim>\<open>latex\<close>: additional mode that is active in {\LaTeX}
   26.13    document preparation of Isabelle theory sources; allows to provide
   26.14 @@ -338,9 +338,9 @@
   26.15    grammar, where for each argument \<open>i\<close> the syntactic category
   26.16    is determined by \<open>\<tau>\<^sub>i\<close> (with priority \<open>p\<^sub>i\<close>), and the
   26.17    result category is determined from \<open>\<tau>\<close> (with priority \<open>p\<close>).  Priority specifications are optional, with default 0 for
   26.18 -  arguments and 1000 for the result.\footnote{Omitting priorities is
   26.19 +  arguments and 1000 for the result.\<^footnote>\<open>Omitting priorities is
   26.20    prone to syntactic ambiguities unless the delimiter tokens determine
   26.21 -  fully bracketed notation, as in \<open>if _ then _ else _ fi\<close>.}
   26.22 +  fully bracketed notation, as in \<open>if _ then _ else _ fi\<close>.\<close>
   26.23  
   26.24    Since \<open>\<tau>\<close> may be again a function type, the constant
   26.25    type scheme may have more argument positions than the mixfix
   26.26 @@ -1213,10 +1213,10 @@
   26.27    side-conditions:
   26.28  
   26.29      \<^item> Rules must be left linear: \<open>lhs\<close> must not contain
   26.30 -    repeated variables.\footnote{The deeper reason for this is that AST
   26.31 +    repeated variables.\<^footnote>\<open>The deeper reason for this is that AST
   26.32      equality is not well-defined: different occurrences of the ``same''
   26.33      AST could be decorated differently by accidental type-constraints or
   26.34 -    source position information, for example.}
   26.35 +    source position information, for example.\<close>
   26.36  
   26.37      \<^item> Every variable in \<open>rhs\<close> must also occur in \<open>lhs\<close>.
   26.38  
    27.1 --- a/src/Doc/Isar_Ref/Outer_Syntax.thy	Tue Nov 10 14:18:41 2015 +0000
    27.2 +++ b/src/Doc/Isar_Ref/Outer_Syntax.thy	Tue Nov 10 14:43:29 2015 +0000
    27.3 @@ -223,17 +223,18 @@
    27.4  
    27.5  subsection \<open>Comments \label{sec:comments}\<close>
    27.6  
    27.7 -text \<open>Large chunks of plain @{syntax text} are usually given @{syntax
    27.8 -  verbatim}, i.e.\ enclosed in \<^verbatim>\<open>{*\<close>~\<open>\<dots>\<close>~\<^verbatim>\<open>*}\<close>,
    27.9 -  or as @{syntax cartouche} \<open>\<open>\<dots>\<close>\<close>. For convenience, any of the
   27.10 -  smaller text units conforming to @{syntax nameref} are admitted as well. A
   27.11 -  marginal @{syntax comment} is of the form \<^verbatim>\<open>--\<close>~@{syntax text}.
   27.12 -  Any number of these may occur within Isabelle/Isar commands.
   27.13 +text \<open>
   27.14 +  Large chunks of plain @{syntax text} are usually given @{syntax verbatim},
   27.15 +  i.e.\ enclosed in \<^verbatim>\<open>{*\<close>~\<open>\<dots>\<close>~\<^verbatim>\<open>*}\<close>, or as @{syntax cartouche} \<open>\<open>\<dots>\<close>\<close>. For
   27.16 +  convenience, any of the smaller text units conforming to @{syntax nameref}
   27.17 +  are admitted as well. A marginal @{syntax comment} is of the form
   27.18 +  \<^verbatim>\<open>--\<close>~@{syntax text} or \<^verbatim>\<open>\<comment>\<close>~@{syntax text}. Any number of these may occur
   27.19 +  within Isabelle/Isar commands.
   27.20  
   27.21    @{rail \<open>
   27.22      @{syntax_def text}: @{syntax verbatim} | @{syntax cartouche} | @{syntax nameref}
   27.23      ;
   27.24 -    @{syntax_def comment}: '--' @{syntax text}
   27.25 +    @{syntax_def comment}: ('--' | @'\<comment>') @{syntax text}
   27.26    \<close>}
   27.27  \<close>
   27.28  
    28.1 --- a/src/Doc/Isar_Ref/Proof.thy	Tue Nov 10 14:18:41 2015 +0000
    28.2 +++ b/src/Doc/Isar_Ref/Proof.thy	Tue Nov 10 14:43:29 2015 +0000
    28.3 @@ -530,8 +530,8 @@
    28.4  
    28.5    \<^medskip>
    28.6    The Isar calculation proof commands may be defined as
    28.7 -  follows:\footnote{We suppress internal bookkeeping such as proper
    28.8 -  handling of block-structure.}
    28.9 +  follows:\<^footnote>\<open>We suppress internal bookkeeping such as proper
   28.10 +  handling of block-structure.\<close>
   28.11  
   28.12    \begin{matharray}{rcl}
   28.13      @{command "also"}\<open>\<^sub>0\<close> & \equiv & @{command "note"}~\<open>calculation = this\<close> \\
   28.14 @@ -718,9 +718,9 @@
   28.15    If the goal had been \<open>show\<close> (or \<open>thus\<close>), some
   28.16    pending sub-goal is solved as well by the rule resulting from the
   28.17    result \<^emph>\<open>exported\<close> into the enclosing goal context.  Thus \<open>qed\<close> may fail for two reasons: either \<open>m\<^sub>2\<close> fails, or the
   28.18 -  resulting rule does not fit to any pending goal\footnote{This
   28.19 +  resulting rule does not fit to any pending goal\<^footnote>\<open>This
   28.20    includes any additional ``strong'' assumptions as introduced by
   28.21 -  @{command "assume"}.} of the enclosing context.  Debugging such a
   28.22 +  @{command "assume"}.\<close> of the enclosing context.  Debugging such a
   28.23    situation might involve temporarily changing @{command "show"} into
   28.24    @{command "have"}, or weakening the local context by replacing
   28.25    occurrences of @{command "assume"} by @{command "presume"}.
    29.1 --- a/src/Doc/Isar_Ref/Spec.thy	Tue Nov 10 14:18:41 2015 +0000
    29.2 +++ b/src/Doc/Isar_Ref/Spec.thy	Tue Nov 10 14:43:29 2015 +0000
    29.3 @@ -462,46 +462,41 @@
    29.4  subsection \<open>Locale expressions \label{sec:locale-expr}\<close>
    29.5  
    29.6  text \<open>
    29.7 -  A \<^emph>\<open>locale expression\<close> denotes a context composed of instances
    29.8 -  of existing locales.  The context consists of the declaration
    29.9 -  elements from the locale instances.  Redundant locale instances are
   29.10 -  omitted according to roundup.
   29.11 +  A \<^emph>\<open>locale expression\<close> denotes a context composed of instances of existing
   29.12 +  locales. The context consists of the declaration elements from the locale
   29.13 +  instances. Redundant locale instances are omitted according to roundup.
   29.14  
   29.15    @{rail \<open>
   29.16      @{syntax_def locale_expr}: (instance + '+') @{syntax for_fixes}
   29.17      ;
   29.18      instance: (qualifier ':')? @{syntax nameref} (pos_insts | named_insts)
   29.19      ;
   29.20 -    qualifier: @{syntax name} ('?' | '!')?
   29.21 +    qualifier: @{syntax name} ('?')?
   29.22      ;
   29.23      pos_insts: ('_' | @{syntax term})*
   29.24      ;
   29.25      named_insts: @'where' (@{syntax name} '=' @{syntax term} + @'and')
   29.26    \<close>}
   29.27  
   29.28 -  A locale instance consists of a reference to a locale and either
   29.29 -  positional or named parameter instantiations.  Identical
   29.30 -  instantiations (that is, those that instantiate a parameter by itself)
   29.31 -  may be omitted.  The notation `\<open>_\<close>' enables to omit the
   29.32 -  instantiation for a parameter inside a positional instantiation.
   29.33 +  A locale instance consists of a reference to a locale and either positional
   29.34 +  or named parameter instantiations. Identical instantiations (that is, those
   29.35 +  that instantiate a parameter by itself) may be omitted. The notation ``\<open>_\<close>''
   29.36 +  enables to omit the instantiation for a parameter inside a positional
   29.37 +  instantiation.
   29.38  
   29.39 -  Terms in instantiations are from the context the locale expressions
   29.40 -  is declared in.  Local names may be added to this context with the
   29.41 -  optional @{keyword "for"} clause.  This is useful for shadowing names
   29.42 -  bound in outer contexts, and for declaring syntax.  In addition,
   29.43 -  syntax declarations from one instance are effective when parsing
   29.44 -  subsequent instances of the same expression.
   29.45 +  Terms in instantiations are from the context the locale expressions is
   29.46 +  declared in. Local names may be added to this context with the optional
   29.47 +  @{keyword "for"} clause. This is useful for shadowing names bound in outer
   29.48 +  contexts, and for declaring syntax. In addition, syntax declarations from
   29.49 +  one instance are effective when parsing subsequent instances of the same
   29.50 +  expression.
   29.51  
   29.52 -  Instances have an optional qualifier which applies to names in
   29.53 -  declarations.  Names include local definitions and theorem names.
   29.54 -  If present, the qualifier itself is either optional
   29.55 -  (``\<^verbatim>\<open>?\<close>''), which means that it may be omitted on input of the
   29.56 -  qualified name, or mandatory (``\<^verbatim>\<open>!\<close>'').  If neither
   29.57 -  ``\<^verbatim>\<open>?\<close>'' nor ``\<^verbatim>\<open>!\<close>'' are present, the command's default
   29.58 -  is used.  For @{command "interpretation"} and @{command "interpret"}
   29.59 -  the default is ``mandatory'', for @{command "locale"} and @{command
   29.60 -  "sublocale"} the default is ``optional''.  Qualifiers play no role
   29.61 -  in determining whether one locale instance subsumes another.
   29.62 +  Instances have an optional qualifier which applies to names in declarations.
   29.63 +  Names include local definitions and theorem names. If present, the qualifier
   29.64 +  itself is either mandatory (default) or non-mandatory (when followed by
   29.65 +  ``\<^verbatim>\<open>?\<close>''). Non-mandatory means that the qualifier may be omitted on input.
   29.66 +  Qualifiers only affect name spaces; they play no role in determining whether
   29.67 +  one locale instance subsumes another.
   29.68  \<close>
   29.69  
   29.70  
   29.71 @@ -678,10 +673,10 @@
   29.72      @@{command print_interps} @{syntax nameref}
   29.73      ;
   29.74  
   29.75 -    equations: @'where' (@{syntax thmdecl}? @{syntax prop} + @'and')
   29.76 +    equations: @'rewrites' (@{syntax thmdecl}? @{syntax prop} + @'and')
   29.77    \<close>}
   29.78  
   29.79 -  \<^descr> @{command "interpretation"}~\<open>expr \<WHERE> eqns\<close>
   29.80 +  \<^descr> @{command "interpretation"}~\<open>expr\<close>~@{keyword "rewrites"}~\<open>eqns\<close>
   29.81    interprets \<open>expr\<close> in a global or local theory.  The command
   29.82    generates proof obligations for the instantiated specifications.
   29.83    Once these are discharged by the user, instantiated declarations (in
   29.84 @@ -722,14 +717,13 @@
   29.85    concepts introduced through definitions.  The equations must be
   29.86    proved.
   29.87  
   29.88 -  \<^descr> @{command "interpret"}~\<open>expr \<WHERE> eqns\<close> interprets
   29.89 +  \<^descr> @{command "interpret"}~\<open>expr\<close>~@{keyword "rewrites"}~\<open>eqns\<close> interprets
   29.90    \<open>expr\<close> in the proof context and is otherwise similar to
   29.91    interpretation in local theories.  Note that for @{command
   29.92    "interpret"} the \<open>eqns\<close> should be
   29.93    explicitly universally quantified.
   29.94  
   29.95 -  \<^descr> @{command "sublocale"}~\<open>name \<subseteq> expr \<WHERE>
   29.96 -  eqns\<close>
   29.97 +  \<^descr> @{command "sublocale"}~\<open>name \<subseteq> expr\<close>~@{keyword "rewrites"}~\<open>eqns\<close>
   29.98    interprets \<open>expr\<close> in the locale \<open>name\<close>.  A proof that
   29.99    the specification of \<open>name\<close> implies the specification of
  29.100    \<open>expr\<close> is required.  As in the localized version of the
  29.101 @@ -828,10 +822,10 @@
  29.102      ;
  29.103      definitions: @'defining' (@{syntax thmdecl}? @{syntax name} \<newline>
  29.104        @{syntax mixfix}? @'=' @{syntax term} + @'and');
  29.105 -    equations: @'where' (@{syntax thmdecl}? @{syntax prop} + @'and')
  29.106 +    equations: @'rewrites' (@{syntax thmdecl}? @{syntax prop} + @'and')
  29.107    \<close>}
  29.108  
  29.109 -  \<^descr> @{command "permanent_interpretation"}~\<open>expr \<DEFINING> defs \<WHERE> eqns\<close>
  29.110 +  \<^descr> @{command "permanent_interpretation"}~\<open>expr \<DEFINING> defs\<close>~@{keyword "rewrites"}~\<open>eqns\<close>
  29.111    interprets \<open>expr\<close> in the current local theory.  The command
  29.112    generates proof obligations for the instantiated specifications.
  29.113    Instantiated declarations (in particular, facts) are added to the
    30.1 --- a/src/Doc/Isar_Ref/Synopsis.thy	Tue Nov 10 14:18:41 2015 +0000
    30.2 +++ b/src/Doc/Isar_Ref/Synopsis.thy	Tue Nov 10 14:43:29 2015 +0000
    30.3 @@ -17,11 +17,11 @@
    30.4  notepad
    30.5  begin
    30.6    txt \<open>Locally fixed entities:\<close>
    30.7 -  fix x   -- \<open>local constant, without any type information yet\<close>
    30.8 -  fix x :: 'a  -- \<open>variant with explicit type-constraint for subsequent use\<close>
    30.9 +  fix x   \<comment> \<open>local constant, without any type information yet\<close>
   30.10 +  fix x :: 'a  \<comment> \<open>variant with explicit type-constraint for subsequent use\<close>
   30.11  
   30.12    fix a b
   30.13 -  assume "a = b"  -- \<open>type assignment at first occurrence in concrete term\<close>
   30.14 +  assume "a = b"  \<comment> \<open>type assignment at first occurrence in concrete term\<close>
   30.15  
   30.16    txt \<open>Definitions (non-polymorphic):\<close>
   30.17    def x \<equiv> "t::'a"
   30.18 @@ -234,7 +234,7 @@
   30.19    proof -
   30.20      term ?thesis
   30.21      show ?thesis sorry
   30.22 -    term ?thesis  -- \<open>static!\<close>
   30.23 +    term ?thesis  \<comment> \<open>static!\<close>
   30.24    qed
   30.25    term "\<dots>"
   30.26    thm this
   30.27 @@ -345,7 +345,7 @@
   30.28    moreover
   30.29    { assume C have R sorry }
   30.30    ultimately
   30.31 -  have R by blast  -- \<open>``big-bang integration'' of proof blocks (occasionally fragile)\<close>
   30.32 +  have R by blast  \<comment> \<open>``big-bang integration'' of proof blocks (occasionally fragile)\<close>
   30.33  end
   30.34  
   30.35  
   30.36 @@ -364,7 +364,7 @@
   30.37  begin
   30.38    fix n :: nat
   30.39    have "P n"
   30.40 -  proof (rule nat.induct)  -- \<open>fragile rule application!\<close>
   30.41 +  proof (rule nat.induct)  \<comment> \<open>fragile rule application!\<close>
   30.42      show "P 0" sorry
   30.43    next
   30.44      fix n :: nat
   30.45 @@ -503,7 +503,7 @@
   30.46      from \<open>A x 0\<close> show "Q x 0" sorry
   30.47    next
   30.48      case (Suc n)
   30.49 -    from \<open>\<And>x. A x n \<Longrightarrow> Q x n\<close>  -- \<open>arbitrary instances can be produced here\<close>
   30.50 +    from \<open>\<And>x. A x n \<Longrightarrow> Q x n\<close>  \<comment> \<open>arbitrary instances can be produced here\<close>
   30.51        and \<open>A x (Suc n)\<close> show "Q x (Suc n)" sorry
   30.52    qed
   30.53  end
   30.54 @@ -675,9 +675,9 @@
   30.55  begin
   30.56    assume a: A and b: B
   30.57    thm conjI
   30.58 -  thm conjI [of A B]  -- "instantiation"
   30.59 -  thm conjI [of A B, OF a b]  -- "instantiation and composition"
   30.60 -  thm conjI [OF a b]  -- "composition via unification (trivial)"
   30.61 +  thm conjI [of A B]  \<comment> "instantiation"
   30.62 +  thm conjI [of A B, OF a b]  \<comment> "instantiation and composition"
   30.63 +  thm conjI [OF a b]  \<comment> "composition via unification (trivial)"
   30.64    thm conjI [OF \<open>A\<close> \<open>B\<close>]
   30.65  
   30.66    thm conjI [OF disjI1]
   30.67 @@ -710,9 +710,9 @@
   30.68        fix x
   30.69        assume "A x"
   30.70        show "B x" sorry
   30.71 -    } -- "implicit block structure made explicit"
   30.72 +    } \<comment> "implicit block structure made explicit"
   30.73      note \<open>\<And>x. A x \<Longrightarrow> B x\<close>
   30.74 -      -- "side exit for the resulting rule"
   30.75 +      \<comment> "side exit for the resulting rule"
   30.76    qed
   30.77  end
   30.78  
   30.79 @@ -726,12 +726,12 @@
   30.80  
   30.81  notepad
   30.82  begin
   30.83 -  assume r1: "A \<Longrightarrow> B \<Longrightarrow> C"  -- \<open>simple rule (Horn clause)\<close>
   30.84 +  assume r1: "A \<Longrightarrow> B \<Longrightarrow> C"  \<comment> \<open>simple rule (Horn clause)\<close>
   30.85  
   30.86 -  have A sorry  -- "prefix of facts via outer sub-proof"
   30.87 +  have A sorry  \<comment> "prefix of facts via outer sub-proof"
   30.88    then have C
   30.89    proof (rule r1)
   30.90 -    show B sorry  -- "remaining rule premises via inner sub-proof"
   30.91 +    show B sorry  \<comment> "remaining rule premises via inner sub-proof"
   30.92    qed
   30.93  
   30.94    have C
   30.95 @@ -750,7 +750,7 @@
   30.96  
   30.97  next
   30.98  
   30.99 -  assume r2: "A \<Longrightarrow> (\<And>x. B1 x \<Longrightarrow> B2 x) \<Longrightarrow> C"  -- \<open>nested rule\<close>
  30.100 +  assume r2: "A \<Longrightarrow> (\<And>x. B1 x \<Longrightarrow> B2 x) \<Longrightarrow> C"  \<comment> \<open>nested rule\<close>
  30.101  
  30.102    have A sorry
  30.103    then have C
  30.104 @@ -850,31 +850,31 @@
  30.105  notepad
  30.106  begin
  30.107    have "A \<and> B"
  30.108 -  proof  -- \<open>two strictly isolated subproofs\<close>
  30.109 +  proof  \<comment> \<open>two strictly isolated subproofs\<close>
  30.110      show A sorry
  30.111    next
  30.112      show B sorry
  30.113    qed
  30.114  
  30.115    have "A \<and> B"
  30.116 -  proof  -- \<open>one simultaneous sub-proof\<close>
  30.117 +  proof  \<comment> \<open>one simultaneous sub-proof\<close>
  30.118      show A and B sorry
  30.119    qed
  30.120  
  30.121    have "A \<and> B"
  30.122 -  proof  -- \<open>two subproofs in the same context\<close>
  30.123 +  proof  \<comment> \<open>two subproofs in the same context\<close>
  30.124      show A sorry
  30.125      show B sorry
  30.126    qed
  30.127  
  30.128    have "A \<and> B"
  30.129 -  proof  -- \<open>swapped order\<close>
  30.130 +  proof  \<comment> \<open>swapped order\<close>
  30.131      show B sorry
  30.132      show A sorry
  30.133    qed
  30.134  
  30.135    have "A \<and> B"
  30.136 -  proof  -- \<open>sequential subproofs\<close>
  30.137 +  proof  \<comment> \<open>sequential subproofs\<close>
  30.138      show A sorry
  30.139      show B using \<open>A\<close> sorry
  30.140    qed
  30.141 @@ -941,9 +941,9 @@
  30.142    following typical representatives:
  30.143  \<close>
  30.144  
  30.145 -thm exE     -- \<open>local parameter\<close>
  30.146 -thm conjE   -- \<open>local premises\<close>
  30.147 -thm disjE   -- \<open>split into cases\<close>
  30.148 +thm exE     \<comment> \<open>local parameter\<close>
  30.149 +thm conjE   \<comment> \<open>local premises\<close>
  30.150 +thm disjE   \<comment> \<open>split into cases\<close>
  30.151  
  30.152  text \<open>
  30.153    Combining these characteristics leads to the following general scheme
  30.154 @@ -1001,7 +1001,7 @@
  30.155  print_statement disjE
  30.156  
  30.157  lemma
  30.158 -  assumes A1 and A2  -- \<open>assumptions\<close>
  30.159 +  assumes A1 and A2  \<comment> \<open>assumptions\<close>
  30.160    obtains
  30.161      (case1)  x y where "B1 x y" and "C1 x y"
  30.162    | (case2)  x y where "B2 x y" and "C2 x y"
    31.1 --- a/src/Doc/Isar_Ref/document/style.sty	Tue Nov 10 14:18:41 2015 +0000
    31.2 +++ b/src/Doc/Isar_Ref/document/style.sty	Tue Nov 10 14:43:29 2015 +0000
    31.3 @@ -40,8 +40,6 @@
    31.4  
    31.5  \isabellestyle{literalunderscore}
    31.6  
    31.7 -\newcommand{\isasymdash}{\isatext{\mbox{-}}}
    31.8 -
    31.9  \railtermfont{\isabellestyle{tt}}
   31.10  \railnontermfont{\isabellestyle{literalunderscore}}
   31.11  \railnamefont{\isabellestyle{literalunderscore}}
    32.1 --- a/src/Doc/JEdit/JEdit.thy	Tue Nov 10 14:18:41 2015 +0000
    32.2 +++ b/src/Doc/JEdit/JEdit.thy	Tue Nov 10 14:43:29 2015 +0000
    32.3 @@ -9,52 +9,50 @@
    32.4  section \<open>Concepts and terminology\<close>
    32.5  
    32.6  text \<open>
    32.7 -  Isabelle/jEdit is a Prover IDE that integrates \<^emph>\<open>parallel proof
    32.8 -  checking\<close> @{cite "Wenzel:2009" and "Wenzel:2013:ITP"} with
    32.9 -  \<^emph>\<open>asynchronous user interaction\<close> @{cite "Wenzel:2010" and
   32.10 -  "Wenzel:2012:UITP-EPTCS" and "Wenzel:2014:ITP-PIDE" and "Wenzel:2014:UITP"},
   32.11 -  based on a document-oriented approach to \<^emph>\<open>continuous proof processing\<close>
   32.12 -  @{cite "Wenzel:2011:CICM" and "Wenzel:2012"}. Many concepts and system
   32.13 -  components are fit together in order to make this work. The main building
   32.14 -  blocks are as follows.
   32.15 +  Isabelle/jEdit is a Prover IDE that integrates \<^emph>\<open>parallel proof checking\<close>
   32.16 +  @{cite "Wenzel:2009" and "Wenzel:2013:ITP"} with \<^emph>\<open>asynchronous user
   32.17 +  interaction\<close> @{cite "Wenzel:2010" and "Wenzel:2012:UITP-EPTCS" and
   32.18 +  "Wenzel:2014:ITP-PIDE" and "Wenzel:2014:UITP"}, based on a document-oriented
   32.19 +  approach to \<^emph>\<open>continuous proof processing\<close> @{cite "Wenzel:2011:CICM" and
   32.20 +  "Wenzel:2012"}. Many concepts and system components are fit together in
   32.21 +  order to make this work. The main building blocks are as follows.
   32.22  
   32.23 -  \<^descr>[PIDE] is a general framework for Prover IDEs based on Isabelle/Scala.
   32.24 -  It is built around a concept of parallel and asynchronous document
   32.25 -  processing, which is supported natively by the parallel proof engine that is
   32.26 -  implemented in Isabelle/ML. The traditional prover command loop is given up;
   32.27 -  instead there is direct support for editing of source text, with rich formal
   32.28 -  markup for GUI rendering.
   32.29 +    \<^descr>[PIDE] is a general framework for Prover IDEs based on Isabelle/Scala. It
   32.30 +    is built around a concept of parallel and asynchronous document
   32.31 +    processing, which is supported natively by the parallel proof engine that
   32.32 +    is implemented in Isabelle/ML. The traditional prover command loop is
   32.33 +    given up; instead there is direct support for editing of source text, with
   32.34 +    rich formal markup for GUI rendering.
   32.35  
   32.36 -  \<^descr>[Isabelle/ML] is the implementation and extension language of
   32.37 -  Isabelle, see also @{cite "isabelle-implementation"}. It is integrated
   32.38 -  into the logical context of Isabelle/Isar and allows to manipulate
   32.39 -  logical entities directly. Arbitrary add-on tools may be implemented
   32.40 -  for object-logics such as Isabelle/HOL.
   32.41 +    \<^descr>[Isabelle/ML] is the implementation and extension language of Isabelle,
   32.42 +    see also @{cite "isabelle-implementation"}. It is integrated into the
   32.43 +    logical context of Isabelle/Isar and allows to manipulate logical entities
   32.44 +    directly. Arbitrary add-on tools may be implemented for object-logics such
   32.45 +    as Isabelle/HOL.
   32.46  
   32.47 -  \<^descr>[Isabelle/Scala] is the system programming language of
   32.48 -  Isabelle. It extends the pure logical environment of Isabelle/ML
   32.49 -  towards the ``real world'' of graphical user interfaces, text
   32.50 -  editors, IDE frameworks, web services etc.  Special infrastructure
   32.51 -  allows to transfer algebraic datatypes and formatted text easily
   32.52 -  between ML and Scala, using asynchronous protocol commands.
   32.53 +    \<^descr>[Isabelle/Scala] is the system programming language of Isabelle. It
   32.54 +    extends the pure logical environment of Isabelle/ML towards the ``real
   32.55 +    world'' of graphical user interfaces, text editors, IDE frameworks, web
   32.56 +    services etc. Special infrastructure allows to transfer algebraic
   32.57 +    datatypes and formatted text easily between ML and Scala, using
   32.58 +    asynchronous protocol commands.
   32.59  
   32.60 -  \<^descr>[jEdit] is a sophisticated text editor implemented in
   32.61 -  Java.\footnote{@{url "http://www.jedit.org"}} It is easily extensible
   32.62 -  by plugins written in languages that work on the JVM, e.g.\
   32.63 -  Scala\footnote{@{url "http://www.scala-lang.org"}}.
   32.64 +    \<^descr>[jEdit] is a sophisticated text editor implemented in Java.\<^footnote>\<open>@{url
   32.65 +    "http://www.jedit.org"}\<close> It is easily extensible by plugins written in
   32.66 +    languages that work on the JVM, e.g.\ Scala\<^footnote>\<open>@{url
   32.67 +    "http://www.scala-lang.org"}\<close>.
   32.68  
   32.69 -  \<^descr>[Isabelle/jEdit] is the main example application of the PIDE
   32.70 -  framework and the default user-interface for Isabelle. It targets
   32.71 -  both beginners and experts. Technically, Isabelle/jEdit combines a
   32.72 -  slightly modified version of the jEdit code base with a special
   32.73 -  plugin for Isabelle, integrated as standalone application for the
   32.74 -  main operating system platforms: Linux, Windows, Mac OS X.
   32.75 +    \<^descr>[Isabelle/jEdit] is the main example application of the PIDE framework
   32.76 +    and the default user-interface for Isabelle. It targets both beginners and
   32.77 +    experts. Technically, Isabelle/jEdit combines a slightly modified version
   32.78 +    of the jEdit code base with a special plugin for Isabelle, integrated as
   32.79 +    standalone application for the main operating system platforms: Linux,
   32.80 +    Windows, Mac OS X.
   32.81  
   32.82 -
   32.83 -  The subtle differences of Isabelle/ML versus Standard ML,
   32.84 -  Isabelle/Scala versus Scala, Isabelle/jEdit versus jEdit need to be
   32.85 -  taken into account when discussing any of these PIDE building blocks
   32.86 -  in public forums, mailing lists, or even scientific publications.
   32.87 +  The subtle differences of Isabelle/ML versus Standard ML, Isabelle/Scala
   32.88 +  versus Scala, Isabelle/jEdit versus jEdit need to be taken into account when
   32.89 +  discussing any of these PIDE building blocks in public forums, mailing
   32.90 +  lists, or even scientific publications.
   32.91  \<close>
   32.92  
   32.93  
   32.94 @@ -73,31 +71,31 @@
   32.95    the jEdit text editor, while preserving its general look-and-feel as far as
   32.96    possible. The main plugin is called ``Isabelle'' and has its own menu
   32.97    \<^emph>\<open>Plugins~/ Isabelle\<close> with access to several panels (see also
   32.98 -  \secref{sec:dockables}), as well as \<^emph>\<open>Plugins~/ Plugin Options~/
   32.99 -  Isabelle\<close> (see also \secref{sec:options}).
  32.100 +  \secref{sec:dockables}), as well as \<^emph>\<open>Plugins~/ Plugin Options~/ Isabelle\<close>
  32.101 +  (see also \secref{sec:options}).
  32.102  
  32.103    The options allow to specify a logic session name --- the same selector is
  32.104 -  accessible in the \<^emph>\<open>Theories\<close> panel (\secref{sec:theories}). On
  32.105 -  application startup, the selected logic session image is provided
  32.106 -  automatically by the Isabelle build tool @{cite "isabelle-system"}: if it is
  32.107 -  absent or outdated wrt.\ its sources, the build process updates it before
  32.108 -  entering the Prover IDE.  Change of the logic session within Isabelle/jEdit
  32.109 -  requires a restart of the whole application.
  32.110 +  accessible in the \<^emph>\<open>Theories\<close> panel (\secref{sec:theories}). On application
  32.111 +  startup, the selected logic session image is provided automatically by the
  32.112 +  Isabelle build tool @{cite "isabelle-system"}: if it is absent or outdated
  32.113 +  wrt.\ its sources, the build process updates it before entering the Prover
  32.114 +  IDE. Change of the logic session within Isabelle/jEdit requires a restart of
  32.115 +  the whole application.
  32.116  
  32.117    \<^medskip>
  32.118 -  The main job of the Prover IDE is to manage sources and their
  32.119 -  changes, taking the logical structure as a formal document into account (see
  32.120 -  also \secref{sec:document-model}). The editor and the prover are connected
  32.121 +  The main job of the Prover IDE is to manage sources and their changes,
  32.122 +  taking the logical structure as a formal document into account (see also
  32.123 +  \secref{sec:document-model}). The editor and the prover are connected
  32.124    asynchronously in a lock-free manner. The prover is free to organize the
  32.125    checking of the formal text in parallel on multiple cores, and provides
  32.126    feedback via markup, which is rendered in the editor via colors, boxes,
  32.127    squiggly underlines, hyperlinks, popup windows, icons, clickable output etc.
  32.128  
  32.129 -  Using the mouse together with the modifier key \<^verbatim>\<open>CONTROL\<close> (Linux,
  32.130 -  Windows) or \<^verbatim>\<open>COMMAND\<close> (Mac OS X) exposes additional formal content
  32.131 -  via tooltips and/or hyperlinks (see also \secref{sec:tooltips-hyperlinks}).
  32.132 -  Output (in popups etc.) may be explored recursively, using the same
  32.133 -  techniques as in the editor source buffer.
  32.134 +  Using the mouse together with the modifier key \<^verbatim>\<open>CONTROL\<close> (Linux, Windows)
  32.135 +  or \<^verbatim>\<open>COMMAND\<close> (Mac OS X) exposes additional formal content via tooltips
  32.136 +  and/or hyperlinks (see also \secref{sec:tooltips-hyperlinks}). Output (in
  32.137 +  popups etc.) may be explored recursively, using the same techniques as in
  32.138 +  the editor source buffer.
  32.139  
  32.140    Thus the Prover IDE gives an impression of direct access to formal content
  32.141    of the prover within the editor, but in reality only certain aspects are
  32.142 @@ -109,14 +107,13 @@
  32.143  subsection \<open>Documentation\<close>
  32.144  
  32.145  text \<open>
  32.146 -  The \<^emph>\<open>Documentation\<close> panel of Isabelle/jEdit provides access to the
  32.147 -  standard Isabelle documentation: PDF files are opened by regular desktop
  32.148 -  operations of the underlying platform. The section ``Original jEdit
  32.149 -  Documentation'' contains the original \<^emph>\<open>User's Guide\<close> of this
  32.150 -  sophisticated text editor. The same is accessible via the \<^verbatim>\<open>Help\<close>
  32.151 -  menu or \<^verbatim>\<open>F1\<close> keyboard shortcut, using the built-in HTML viewer of
  32.152 -  Java/Swing. The latter also includes \<^emph>\<open>Frequently Asked Questions\<close> and
  32.153 -  documentation of individual plugins.
  32.154 +  The \<^emph>\<open>Documentation\<close> panel of Isabelle/jEdit provides access to the standard
  32.155 +  Isabelle documentation: PDF files are opened by regular desktop operations
  32.156 +  of the underlying platform. The section ``Original jEdit Documentation''
  32.157 +  contains the original \<^emph>\<open>User's Guide\<close> of this sophisticated text editor. The
  32.158 +  same is accessible via the \<^verbatim>\<open>Help\<close> menu or \<^verbatim>\<open>F1\<close> keyboard shortcut, using
  32.159 +  the built-in HTML viewer of Java/Swing. The latter also includes
  32.160 +  \<^emph>\<open>Frequently Asked Questions\<close> and documentation of individual plugins.
  32.161  
  32.162    Most of the information about generic jEdit is relevant for Isabelle/jEdit
  32.163    as well, but one needs to keep in mind that defaults sometimes differ, and
  32.164 @@ -129,9 +126,9 @@
  32.165  subsection \<open>Plugins\<close>
  32.166  
  32.167  text \<open>
  32.168 -  The \<^emph>\<open>Plugin Manager\<close> of jEdit allows to augment editor functionality by
  32.169 -  JVM modules (jars) that are provided by the central plugin repository, which
  32.170 -  is accessible via various mirror sites.
  32.171 +  The \<^emph>\<open>Plugin Manager\<close> of jEdit allows to augment editor functionality by JVM
  32.172 +  modules (jars) that are provided by the central plugin repository, which is
  32.173 +  accessible via various mirror sites.
  32.174  
  32.175    Connecting to the plugin server-infrastructure of the jEdit project allows
  32.176    to update bundled plugins or to add further functionality. This needs to be
  32.177 @@ -142,28 +139,27 @@
  32.178    at a grand scale.
  32.179  
  32.180    \<^medskip>
  32.181 -  The main \<^emph>\<open>Isabelle\<close> plugin is an integral part of
  32.182 -  Isabelle/jEdit and needs to remain active at all times! A few additional
  32.183 -  plugins are bundled with Isabelle/jEdit for convenience or out of necessity,
  32.184 -  notably \<^emph>\<open>Console\<close> with its Isabelle/Scala sub-plugin
  32.185 -  (\secref{sec:scala-console}) and \<^emph>\<open>SideKick\<close> with some Isabelle-specific
  32.186 -  parsers for document tree structure (\secref{sec:sidekick}). The
  32.187 -  \<^emph>\<open>Navigator\<close> plugin is particularly important for hyperlinks within the
  32.188 -  formal document-model (\secref{sec:tooltips-hyperlinks}). Further plugins
  32.189 -  (e.g.\ \<^emph>\<open>ErrorList\<close>, \<^emph>\<open>Code2HTML\<close>) are included to saturate the
  32.190 -  dependencies of bundled plugins, but have no particular use in
  32.191 -  Isabelle/jEdit.
  32.192 +  The main \<^emph>\<open>Isabelle\<close> plugin is an integral part of Isabelle/jEdit and needs
  32.193 +  to remain active at all times! A few additional plugins are bundled with
  32.194 +  Isabelle/jEdit for convenience or out of necessity, notably \<^emph>\<open>Console\<close> with
  32.195 +  its Isabelle/Scala sub-plugin (\secref{sec:scala-console}) and \<^emph>\<open>SideKick\<close>
  32.196 +  with some Isabelle-specific parsers for document tree structure
  32.197 +  (\secref{sec:sidekick}). The \<^emph>\<open>Navigator\<close> plugin is particularly important
  32.198 +  for hyperlinks within the formal document-model
  32.199 +  (\secref{sec:tooltips-hyperlinks}). Further plugins (e.g.\ \<^emph>\<open>ErrorList\<close>,
  32.200 +  \<^emph>\<open>Code2HTML\<close>) are included to saturate the dependencies of bundled plugins,
  32.201 +  but have no particular use in Isabelle/jEdit.
  32.202  \<close>
  32.203  
  32.204  
  32.205  subsection \<open>Options \label{sec:options}\<close>
  32.206  
  32.207 -text \<open>Both jEdit and Isabelle have distinctive management of
  32.208 -  persistent options.
  32.209 +text \<open>
  32.210 +  Both jEdit and Isabelle have distinctive management of persistent options.
  32.211  
  32.212 -  Regular jEdit options are accessible via the dialogs \<^emph>\<open>Utilities~/
  32.213 -  Global Options\<close> or \<^emph>\<open>Plugins~/ Plugin Options\<close>, with a second chance to
  32.214 -  flip the two within the central options dialog. Changes are stored in
  32.215 +  Regular jEdit options are accessible via the dialogs \<^emph>\<open>Utilities~/ Global
  32.216 +  Options\<close> or \<^emph>\<open>Plugins~/ Plugin Options\<close>, with a second chance to flip the
  32.217 +  two within the central options dialog. Changes are stored in
  32.218    @{file_unchecked "$ISABELLE_HOME_USER/jedit/properties"} and
  32.219    @{file_unchecked "$ISABELLE_HOME_USER/jedit/keymaps"}.
  32.220  
  32.221 @@ -173,17 +169,17 @@
  32.222    coverage of sessions and command-line tools like @{tool build} or @{tool
  32.223    options}.
  32.224  
  32.225 -  Those Isabelle options that are declared as \<^bold>\<open>public\<close> are configurable
  32.226 -  in Isabelle/jEdit via \<^emph>\<open>Plugin Options~/ Isabelle~/ General\<close>. Moreover,
  32.227 -  there are various options for rendering of document content, which are
  32.228 -  configurable via \<^emph>\<open>Plugin Options~/ Isabelle~/ Rendering\<close>. Thus
  32.229 -  \<^emph>\<open>Plugin Options~/ Isabelle\<close> in jEdit provides a view on a subset of
  32.230 -  Isabelle system options. Note that some of these options affect general
  32.231 -  parameters that are relevant outside Isabelle/jEdit as well, e.g.\
  32.232 -  @{system_option threads} or @{system_option parallel_proofs} for the
  32.233 -  Isabelle build tool @{cite "isabelle-system"}, but it is possible to use the
  32.234 -  settings variable @{setting ISABELLE_BUILD_OPTIONS} to change defaults for
  32.235 -  batch builds without affecting Isabelle/jEdit.
  32.236 +  Those Isabelle options that are declared as \<^bold>\<open>public\<close> are configurable in
  32.237 +  Isabelle/jEdit via \<^emph>\<open>Plugin Options~/ Isabelle~/ General\<close>. Moreover, there
  32.238 +  are various options for rendering of document content, which are
  32.239 +  configurable via \<^emph>\<open>Plugin Options~/ Isabelle~/ Rendering\<close>. Thus \<^emph>\<open>Plugin
  32.240 +  Options~/ Isabelle\<close> in jEdit provides a view on a subset of Isabelle system
  32.241 +  options. Note that some of these options affect general parameters that are
  32.242 +  relevant outside Isabelle/jEdit as well, e.g.\ @{system_option threads} or
  32.243 +  @{system_option parallel_proofs} for the Isabelle build tool @{cite
  32.244 +  "isabelle-system"}, but it is possible to use the settings variable
  32.245 +  @{setting ISABELLE_BUILD_OPTIONS} to change defaults for batch builds
  32.246 +  without affecting Isabelle/jEdit.
  32.247  
  32.248    The jEdit action @{action_def isabelle.options} opens the options dialog for
  32.249    the Isabelle plugin; it can be mapped to editor GUI elements as usual.
  32.250 @@ -193,24 +189,25 @@
  32.251    Isabelle/jEdit. Editing the machine-generated @{file_unchecked
  32.252    "$ISABELLE_HOME_USER/jedit/properties"} or @{file_unchecked
  32.253    "$ISABELLE_HOME_USER/etc/preferences"} manually while the application is
  32.254 -  running is likely to cause surprise due to lost update!\<close>
  32.255 +  running is likely to cause surprise due to lost update!
  32.256 +\<close>
  32.257  
  32.258  
  32.259  subsection \<open>Keymaps\<close>
  32.260  
  32.261 -text \<open>Keyboard shortcuts used to be managed as jEdit properties in
  32.262 -  the past, but recent versions (2013) have a separate concept of
  32.263 -  \<^emph>\<open>keymap\<close> that is configurable via \<^emph>\<open>Global Options~/
  32.264 -  Shortcuts\<close>.  The \<^verbatim>\<open>imported\<close> keymap is derived from the
  32.265 -  initial environment of properties that is available at the first
  32.266 -  start of the editor; afterwards the keymap file takes precedence.
  32.267 +text \<open>
  32.268 +  Keyboard shortcuts used to be managed as jEdit properties in the past, but
  32.269 +  recent versions (2013) have a separate concept of \<^emph>\<open>keymap\<close> that is
  32.270 +  configurable via \<^emph>\<open>Global Options~/ Shortcuts\<close>. The \<^verbatim>\<open>imported\<close> keymap is
  32.271 +  derived from the initial environment of properties that is available at the
  32.272 +  first start of the editor; afterwards the keymap file takes precedence.
  32.273  
  32.274    This is relevant for Isabelle/jEdit due to various fine-tuning of default
  32.275    properties, and additional keyboard shortcuts for Isabelle-specific
  32.276    functionality. Users may change their keymap later, but need to copy some
  32.277    keyboard shortcuts manually (see also @{file_unchecked
  32.278 -  "$ISABELLE_HOME_USER/jedit/keymaps"} versus \<^verbatim>\<open>shortcut\<close> properties
  32.279 -  in @{file "$ISABELLE_HOME/src/Tools/jEdit/src/jEdit.props"}).
  32.280 +  "$ISABELLE_HOME_USER/jedit/keymaps"} versus \<^verbatim>\<open>shortcut\<close> properties in @{file
  32.281 +  "$ISABELLE_HOME/src/Tools/jEdit/src/jEdit.props"}).
  32.282  \<close>
  32.283  
  32.284  
  32.285 @@ -239,33 +236,32 @@
  32.286    Start jEdit with Isabelle plugin setup and open FILES
  32.287    (default "$USER_HOME/Scratch.thy" or ":" for empty buffer).\<close>}
  32.288  
  32.289 -  The \<^verbatim>\<open>-l\<close> option specifies the session name of the logic
  32.290 -  image to be used for proof processing.  Additional session root
  32.291 -  directories may be included via option \<^verbatim>\<open>-d\<close> to augment
  32.292 -  that name space of @{tool build} @{cite "isabelle-system"}.
  32.293 +  The \<^verbatim>\<open>-l\<close> option specifies the session name of the logic image to be used
  32.294 +  for proof processing. Additional session root directories may be included
  32.295 +  via option \<^verbatim>\<open>-d\<close> to augment that name space of @{tool build} @{cite
  32.296 +  "isabelle-system"}.
  32.297  
  32.298 -  By default, the specified image is checked and built on demand. The
  32.299 -  \<^verbatim>\<open>-s\<close> option determines where to store the result session image
  32.300 -  of @{tool build}. The \<^verbatim>\<open>-n\<close> option bypasses the implicit build
  32.301 -  process for the selected session image.
  32.302 +  By default, the specified image is checked and built on demand. The \<^verbatim>\<open>-s\<close>
  32.303 +  option determines where to store the result session image of @{tool build}.
  32.304 +  The \<^verbatim>\<open>-n\<close> option bypasses the implicit build process for the selected
  32.305 +  session image.
  32.306  
  32.307 -  The \<^verbatim>\<open>-m\<close> option specifies additional print modes for the prover
  32.308 -  process. Note that the system option @{system_option_ref jedit_print_mode}
  32.309 -  allows to do the same persistently (e.g.\ via the \<^emph>\<open>Plugin Options\<close>
  32.310 -  dialog of Isabelle/jEdit), without requiring command-line invocation.
  32.311 +  The \<^verbatim>\<open>-m\<close> option specifies additional print modes for the prover process.
  32.312 +  Note that the system option @{system_option_ref jedit_print_mode} allows to
  32.313 +  do the same persistently (e.g.\ via the \<^emph>\<open>Plugin Options\<close> dialog of
  32.314 +  Isabelle/jEdit), without requiring command-line invocation.
  32.315  
  32.316 -  The \<^verbatim>\<open>-J\<close> and \<^verbatim>\<open>-j\<close> options allow to pass additional
  32.317 -  low-level options to the JVM or jEdit, respectively. The defaults are
  32.318 -  provided by the Isabelle settings environment @{cite "isabelle-system"}, but
  32.319 -  note that these only work for the command-line tool described here, and not
  32.320 -  the regular application.
  32.321 +  The \<^verbatim>\<open>-J\<close> and \<^verbatim>\<open>-j\<close> options allow to pass additional low-level options to
  32.322 +  the JVM or jEdit, respectively. The defaults are provided by the Isabelle
  32.323 +  settings environment @{cite "isabelle-system"}, but note that these only
  32.324 +  work for the command-line tool described here, and not the regular
  32.325 +  application.
  32.326  
  32.327 -  The \<^verbatim>\<open>-b\<close> and \<^verbatim>\<open>-f\<close> options control the self-build
  32.328 -  mechanism of Isabelle/jEdit. This is only relevant for building from
  32.329 -  sources, which also requires an auxiliary \<^verbatim>\<open>jedit_build\<close> component
  32.330 -  from @{url "http://isabelle.in.tum.de/components"}. The official
  32.331 -  Isabelle release already includes a pre-built version of Isabelle/jEdit.
  32.332 -\<close>
  32.333 +  The \<^verbatim>\<open>-b\<close> and \<^verbatim>\<open>-f\<close> options control the self-build mechanism of
  32.334 +  Isabelle/jEdit. This is only relevant for building from sources, which also
  32.335 +  requires an auxiliary \<^verbatim>\<open>jedit_build\<close> component from @{url
  32.336 +  "http://isabelle.in.tum.de/components"}. The official Isabelle release
  32.337 +  already includes a pre-built version of Isabelle/jEdit. \<close>
  32.338  
  32.339  
  32.340  chapter \<open>Augmented jEdit functionality\<close>
  32.341 @@ -283,39 +279,35 @@
  32.342    Isabelle/jEdit enables platform-specific look-and-feel by default as
  32.343    follows.
  32.344  
  32.345 -  \<^descr>[Linux:] The platform-independent \<^emph>\<open>Metal\<close> is used by
  32.346 -  default.
  32.347 +    \<^descr>[Linux:] The platform-independent \<^emph>\<open>Metal\<close> is used by default.
  32.348  
  32.349 -  \<^emph>\<open>GTK+\<close> also works under the side-condition that the overall GTK theme
  32.350 -  is selected in a Swing-friendly way.\footnote{GTK support in Java/Swing was
  32.351 -  once marketed aggressively by Sun, but never quite finished. Today (2015) it
  32.352 -  is lagging behind further development of Swing and GTK. The graphics
  32.353 -  rendering performance can be worse than for other Swing look-and-feels.
  32.354 -  Nonetheless it has its uses for displays with very high resolution (such as
  32.355 -  ``4K'' or ``UHD'' models), because the rendering by the external library is
  32.356 -  subject to global system settings for font scaling.}
  32.357 +    \<^emph>\<open>GTK+\<close> also works under the side-condition that the overall GTK theme is
  32.358 +    selected in a Swing-friendly way.\<^footnote>\<open>GTK support in Java/Swing was once
  32.359 +    marketed aggressively by Sun, but never quite finished. Today (2015) it is
  32.360 +    lagging behind further development of Swing and GTK. The graphics
  32.361 +    rendering performance can be worse than for other Swing look-and-feels.
  32.362 +    Nonetheless it has its uses for displays with very high resolution (such
  32.363 +    as ``4K'' or ``UHD'' models), because the rendering by the external
  32.364 +    library is subject to global system settings for font scaling.\<close>
  32.365  
  32.366 -  \<^descr>[Windows:] Regular \<^emph>\<open>Windows\<close> is used by default, but
  32.367 -  \<^emph>\<open>Windows Classic\<close> also works.
  32.368 -
  32.369 -  \<^descr>[Mac OS X:] Regular \<^emph>\<open>Mac OS X\<close> is used by default.
  32.370 +    \<^descr>[Windows:] Regular \<^emph>\<open>Windows\<close> is used by default, but \<^emph>\<open>Windows Classic\<close>
  32.371 +    also works.
  32.372  
  32.373 -  The bundled \<^emph>\<open>MacOSX\<close> plugin provides various functions that are
  32.374 -  expected from applications on that particular platform: quit from menu or
  32.375 -  dock, preferences menu, drag-and-drop of text files on the application,
  32.376 -  full-screen mode for main editor windows. It is advisable to have the
  32.377 -  \<^emph>\<open>MacOSX\<close> plugin enabled all the time on that platform.
  32.378 +    \<^descr>[Mac OS X:] Regular \<^emph>\<open>Mac OS X\<close> is used by default.
  32.379  
  32.380 +    The bundled \<^emph>\<open>MacOSX\<close> plugin provides various functions that are expected
  32.381 +    from applications on that particular platform: quit from menu or dock,
  32.382 +    preferences menu, drag-and-drop of text files on the application,
  32.383 +    full-screen mode for main editor windows. It is advisable to have the
  32.384 +    \<^emph>\<open>MacOSX\<close> plugin enabled all the time on that platform.
  32.385  
  32.386 -  Users may experiment with different look-and-feels, but need to keep
  32.387 -  in mind that this extra variance of GUI functionality is unlikely to
  32.388 -  work in arbitrary combinations.  The platform-independent
  32.389 -  \<^emph>\<open>Metal\<close> and \<^emph>\<open>Nimbus\<close> should always work.  The historic
  32.390 -  \<^emph>\<open>CDE/Motif\<close> should be ignored.
  32.391 +  Users may experiment with different look-and-feels, but need to keep in mind
  32.392 +  that this extra variance of GUI functionality is unlikely to work in
  32.393 +  arbitrary combinations. The platform-independent \<^emph>\<open>Metal\<close> and \<^emph>\<open>Nimbus\<close>
  32.394 +  should always work. The historic \<^emph>\<open>CDE/Motif\<close> should be ignored.
  32.395  
  32.396 -  After changing the look-and-feel in \<^emph>\<open>Global Options~/
  32.397 -  Appearance\<close>, it is advisable to restart Isabelle/jEdit in order to
  32.398 -  take full effect.
  32.399 +  After changing the look-and-feel in \<^emph>\<open>Global Options~/ Appearance\<close>, it is
  32.400 +  advisable to restart Isabelle/jEdit in order to take full effect.
  32.401  \<close>
  32.402  
  32.403  
  32.404 @@ -326,49 +318,47 @@
  32.405    were considered ``high resolution'' and bitmap fonts with 12 or 14 pixels as
  32.406    adequate for text rendering. Today (2015), we routinely see ``Full HD''
  32.407    monitors at $1920 \times 1080$ pixels, and occasionally ``Ultra HD'' at
  32.408 -  $3840 \times 2160$ or more, but GUI rendering did not really progress
  32.409 -  beyond the old standards.
  32.410 +  $3840 \times 2160$ or more, but GUI rendering did not really progress beyond
  32.411 +  the old standards.
  32.412  
  32.413    Isabelle/jEdit defaults are a compromise for reasonable out-of-the box
  32.414    results on common platforms and medium resolution displays (e.g.\ the ``Full
  32.415    HD'' category). Subsequently there are further hints to improve on that.
  32.416  
  32.417    \<^medskip>
  32.418 -  The \<^bold>\<open>operating-system platform\<close> usually provides some
  32.419 -  configuration for global scaling of text fonts, e.g.\ $120\%$--$250\%$ on
  32.420 -  Windows. Changing that only has a partial effect on GUI rendering;
  32.421 -  satisfactory display quality requires further adjustments.
  32.422 +  The \<^bold>\<open>operating-system platform\<close> usually provides some configuration for
  32.423 +  global scaling of text fonts, e.g.\ $120\%$--$250\%$ on Windows. Changing
  32.424 +  that only has a partial effect on GUI rendering; satisfactory display
  32.425 +  quality requires further adjustments.
  32.426  
  32.427    \<^medskip>
  32.428 -  The Isabelle/jEdit \<^bold>\<open>application\<close> and its plugins provide
  32.429 -  various font properties that are summarized below.
  32.430 +  The Isabelle/jEdit \<^bold>\<open>application\<close> and its plugins provide various font
  32.431 +  properties that are summarized below.
  32.432  
  32.433 -  \<^item> \<^emph>\<open>Global Options / Text Area / Text font\<close>: the main text area
  32.434 -  font, which is also used as reference point for various derived font sizes,
  32.435 -  e.g.\ the Output panel (\secref{sec:output}).
  32.436 +    \<^item> \<^emph>\<open>Global Options / Text Area / Text font\<close>: the main text area font,
  32.437 +    which is also used as reference point for various derived font sizes,
  32.438 +    e.g.\ the Output panel (\secref{sec:output}).
  32.439  
  32.440 -  \<^item> \<^emph>\<open>Global Options / Gutter / Gutter font\<close>: the font for the gutter
  32.441 -  area left of the main text area, e.g.\ relevant for display of line numbers
  32.442 -  (disabled by default).
  32.443 +    \<^item> \<^emph>\<open>Global Options / Gutter / Gutter font\<close>: the font for the gutter area
  32.444 +    left of the main text area, e.g.\ relevant for display of line numbers
  32.445 +    (disabled by default).
  32.446  
  32.447 -  \<^item> \<^emph>\<open>Global Options / Appearance / Button, menu and label font\<close> as
  32.448 -  well as \<^emph>\<open>List and text field font\<close>: this specifies the primary and
  32.449 -  secondary font for the traditional \<^emph>\<open>Metal\<close> look-and-feel
  32.450 -  (\secref{sec:look-and-feel}), which happens to scale better than newer ones
  32.451 -  like \<^emph>\<open>Nimbus\<close>.
  32.452 +    \<^item> \<^emph>\<open>Global Options / Appearance / Button, menu and label font\<close> as well as
  32.453 +    \<^emph>\<open>List and text field font\<close>: this specifies the primary and secondary font
  32.454 +    for the traditional \<^emph>\<open>Metal\<close> look-and-feel (\secref{sec:look-and-feel}),
  32.455 +    which happens to scale better than newer ones like \<^emph>\<open>Nimbus\<close>.
  32.456  
  32.457 -  \<^item> \<^emph>\<open>Plugin Options / Isabelle / General / Reset Font Size\<close>: the main
  32.458 -  text area font size for action @{action_ref "isabelle.reset-font-size"},
  32.459 -  e.g.\ relevant for quick scaling like in major web browsers.
  32.460 +    \<^item> \<^emph>\<open>Plugin Options / Isabelle / General / Reset Font Size\<close>: the main text
  32.461 +    area font size for action @{action_ref "isabelle.reset-font-size"}, e.g.\
  32.462 +    relevant for quick scaling like in major web browsers.
  32.463  
  32.464 -  \<^item> \<^emph>\<open>Plugin Options / Console / General / Font\<close>: the console window
  32.465 -  font, e.g.\ relevant for Isabelle/Scala command-line.
  32.466 -
  32.467 +    \<^item> \<^emph>\<open>Plugin Options / Console / General / Font\<close>: the console window font,
  32.468 +    e.g.\ relevant for Isabelle/Scala command-line.
  32.469  
  32.470 -  In \figref{fig:isabelle-jedit-hdpi} the \<^emph>\<open>Metal\<close> look-and-feel is
  32.471 -  configured with custom fonts at 30 pixels, and the main text area and
  32.472 -  console at 36 pixels. Despite the old-fashioned appearance of \<^emph>\<open>Metal\<close>,
  32.473 -  this leads to decent rendering quality on all platforms.
  32.474 +  In \figref{fig:isabelle-jedit-hdpi} the \<^emph>\<open>Metal\<close> look-and-feel is configured
  32.475 +  with custom fonts at 30 pixels, and the main text area and console at 36
  32.476 +  pixels. Despite the old-fashioned appearance of \<^emph>\<open>Metal\<close>, this leads to
  32.477 +  decent rendering quality on all platforms.
  32.478  
  32.479    \begin{figure}[htb]
  32.480    \begin{center}
  32.481 @@ -387,25 +377,25 @@
  32.482  section \<open>Dockable windows \label{sec:dockables}\<close>
  32.483  
  32.484  text \<open>
  32.485 -  In jEdit terminology, a \<^emph>\<open>view\<close> is an editor window with one or more
  32.486 -  \<^emph>\<open>text areas\<close> that show the content of one or more \<^emph>\<open>buffers\<close>. A
  32.487 -  regular view may be surrounded by \<^emph>\<open>dockable windows\<close> that show
  32.488 -  additional information in arbitrary format, not just text; a \<^emph>\<open>plain
  32.489 -  view\<close> does not allow dockables. The \<^emph>\<open>dockable window manager\<close> of jEdit
  32.490 -  organizes these dockable windows, either as \<^emph>\<open>floating\<close> windows, or
  32.491 -  \<^emph>\<open>docked\<close> panels within one of the four margins of the view. There may
  32.492 -  be any number of floating instances of some dockable window, but at most one
  32.493 -  docked instance; jEdit actions that address \<^emph>\<open>the\<close> dockable window of a
  32.494 -  particular kind refer to the unique docked instance.
  32.495 +  In jEdit terminology, a \<^emph>\<open>view\<close> is an editor window with one or more \<^emph>\<open>text
  32.496 +  areas\<close> that show the content of one or more \<^emph>\<open>buffers\<close>. A regular view may
  32.497 +  be surrounded by \<^emph>\<open>dockable windows\<close> that show additional information in
  32.498 +  arbitrary format, not just text; a \<^emph>\<open>plain view\<close> does not allow dockables.
  32.499 +  The \<^emph>\<open>dockable window manager\<close> of jEdit organizes these dockable windows,
  32.500 +  either as \<^emph>\<open>floating\<close> windows, or \<^emph>\<open>docked\<close> panels within one of the four
  32.501 +  margins of the view. There may be any number of floating instances of some
  32.502 +  dockable window, but at most one docked instance; jEdit actions that address
  32.503 +  \<^emph>\<open>the\<close> dockable window of a particular kind refer to the unique docked
  32.504 +  instance.
  32.505  
  32.506    Dockables are used routinely in jEdit for important functionality like
  32.507 -  \<^emph>\<open>HyperSearch Results\<close> or the \<^emph>\<open>File System Browser\<close>. Plugins often
  32.508 -  provide a central dockable to access their key functionality, which may be
  32.509 -  opened by the user on demand. The Isabelle/jEdit plugin takes this approach
  32.510 -  to the extreme: its plugin menu provides the entry-points to many panels
  32.511 -  that are managed as dockable windows. Some important panels are docked by
  32.512 -  default, e.g.\ \<^emph>\<open>Documentation\<close>, \<^emph>\<open>Output\<close>, \<^emph>\<open>Query\<close>, but the
  32.513 -  user can change this arrangement easily and persistently.
  32.514 +  \<^emph>\<open>HyperSearch Results\<close> or the \<^emph>\<open>File System Browser\<close>. Plugins often provide
  32.515 +  a central dockable to access their key functionality, which may be opened by
  32.516 +  the user on demand. The Isabelle/jEdit plugin takes this approach to the
  32.517 +  extreme: its plugin menu provides the entry-points to many panels that are
  32.518 +  managed as dockable windows. Some important panels are docked by default,
  32.519 +  e.g.\ \<^emph>\<open>Documentation\<close>, \<^emph>\<open>Output\<close>, \<^emph>\<open>Query\<close>, but the user can change this
  32.520 +  arrangement easily and persistently.
  32.521  
  32.522    Compared to plain jEdit, dockable window management in Isabelle/jEdit is
  32.523    slightly augmented according to the the following principles:
  32.524 @@ -439,19 +429,18 @@
  32.525    Isabelle sources consist of \<^emph>\<open>symbols\<close> that extend plain ASCII to allow
  32.526    infinitely many mathematical symbols within the formal sources. This works
  32.527    without depending on particular encodings and varying Unicode
  32.528 -  standards.\footnote{Raw Unicode characters within formal sources would
  32.529 -  compromise portability and reliability in the face of changing
  32.530 -  interpretation of special features of Unicode, such as Combining Characters
  32.531 -  or Bi-directional Text.} See also @{cite "Wenzel:2011:CICM"}.
  32.532 +  standards.\<^footnote>\<open>Raw Unicode characters within formal sources would compromise
  32.533 +  portability and reliability in the face of changing interpretation of
  32.534 +  special features of Unicode, such as Combining Characters or Bi-directional
  32.535 +  Text.\<close> See also @{cite "Wenzel:2011:CICM"}.
  32.536  
  32.537    For the prover back-end, formal text consists of ASCII characters that are
  32.538 -  grouped according to some simple rules, e.g.\ as plain ``\<^verbatim>\<open>a\<close>'' or
  32.539 -  symbolic ``\<^verbatim>\<open>\<alpha>\<close>''. For the editor front-end, a certain subset of
  32.540 -  symbols is rendered physically via Unicode glyphs, in order to show
  32.541 -  ``\<^verbatim>\<open>\<alpha>\<close>'' as ``\<open>\<alpha>\<close>'', for example. This symbol
  32.542 -  interpretation is specified by the Isabelle system distribution in @{file
  32.543 -  "$ISABELLE_HOME/etc/symbols"} and may be augmented by the user in
  32.544 -  @{file_unchecked "$ISABELLE_HOME_USER/etc/symbols"}.
  32.545 +  grouped according to some simple rules, e.g.\ as plain ``\<^verbatim>\<open>a\<close>'' or symbolic
  32.546 +  ``\<^verbatim>\<open>\<alpha>\<close>''. For the editor front-end, a certain subset of symbols is rendered
  32.547 +  physically via Unicode glyphs, in order to show ``\<^verbatim>\<open>\<alpha>\<close>'' as ``\<open>\<alpha>\<close>'', for
  32.548 +  example. This symbol interpretation is specified by the Isabelle system
  32.549 +  distribution in @{file "$ISABELLE_HOME/etc/symbols"} and may be augmented by
  32.550 +  the user in @{file_unchecked "$ISABELLE_HOME_USER/etc/symbols"}.
  32.551  
  32.552    The appendix of @{cite "isabelle-isar-ref"} gives an overview of the
  32.553    standard interpretation of finitely many symbols from the infinite
  32.554 @@ -484,13 +473,13 @@
  32.555  
  32.556    Note that a Java/AWT/Swing application can load additional fonts only if
  32.557    they are not installed on the operating system already! Some outdated
  32.558 -  version of \<^verbatim>\<open>IsabelleText\<close> that happens to be provided by the
  32.559 -  operating system would prevent Isabelle/jEdit to use its bundled version.
  32.560 -  This could lead to missing glyphs (black rectangles), when the system
  32.561 -  version of \<^verbatim>\<open>IsabelleText\<close> is older than the application version.
  32.562 -  This problem can be avoided by refraining to ``install'' any version of
  32.563 -  \<^verbatim>\<open>IsabelleText\<close> in the first place, although it is occasionally
  32.564 -  tempting to use the same font in other applications.
  32.565 +  version of \<^verbatim>\<open>IsabelleText\<close> that happens to be provided by the operating
  32.566 +  system would prevent Isabelle/jEdit to use its bundled version. This could
  32.567 +  lead to missing glyphs (black rectangles), when the system version of
  32.568 +  \<^verbatim>\<open>IsabelleText\<close> is older than the application version. This problem can be
  32.569 +  avoided by refraining to ``install'' any version of \<^verbatim>\<open>IsabelleText\<close> in the
  32.570 +  first place, although it is occasionally tempting to use the same font in
  32.571 +  other applications.
  32.572  \<close>
  32.573  
  32.574  paragraph \<open>Input methods.\<close>
  32.575 @@ -548,17 +537,16 @@
  32.576      \<open>\<notin>\<close> & \<^verbatim>\<open>\notin\<close> & \<^verbatim>\<open>~:\<close> \\
  32.577    \end{tabular}
  32.578    \<^medskip>
  32.579 - 
  32.580 +
  32.581    Note that the above abbreviations refer to the input method. The logical
  32.582    notation provides ASCII alternatives that often coincide, but sometimes
  32.583    deviate. This occasionally causes user confusion with very old-fashioned
  32.584 -  Isabelle source that use ASCII replacement notation like \<^verbatim>\<open>!\<close> or
  32.585 -  \<^verbatim>\<open>ALL\<close> directly in the text.
  32.586 +  Isabelle source that use ASCII replacement notation like \<^verbatim>\<open>!\<close> or \<^verbatim>\<open>ALL\<close>
  32.587 +  directly in the text.
  32.588  
  32.589    On the other hand, coincidence of symbol abbreviations with ASCII
  32.590 -  replacement syntax syntax helps to update old theory sources via
  32.591 -  explicit completion (see also \<^verbatim>\<open>C+b\<close> explained in
  32.592 -  \secref{sec:completion}).
  32.593 +  replacement syntax syntax helps to update old theory sources via explicit
  32.594 +  completion (see also \<^verbatim>\<open>C+b\<close> explained in \secref{sec:completion}).
  32.595  \<close>
  32.596  
  32.597  paragraph \<open>Control symbols.\<close>
  32.598 @@ -596,8 +584,7 @@
  32.599  
  32.600    Isabelle/jEdit provides SideKick parsers for its main mode for theory files,
  32.601    as well as some minor modes for the \<^verbatim>\<open>NEWS\<close> file (see
  32.602 -  \figref{fig:sidekick}), session \<^verbatim>\<open>ROOT\<close> files, and system
  32.603 -  \<^verbatim>\<open>options\<close>.
  32.604 +  \figref{fig:sidekick}), session \<^verbatim>\<open>ROOT\<close> files, and system \<^verbatim>\<open>options\<close>.
  32.605  
  32.606    \begin{figure}[htb]
  32.607    \begin{center}
  32.608 @@ -607,35 +594,33 @@
  32.609    \label{fig:sidekick}
  32.610    \end{figure}
  32.611  
  32.612 -  Moreover, the special SideKick parser \<^verbatim>\<open>isabelle-markup\<close>
  32.613 -  provides access to the full (uninterpreted) markup tree of the PIDE
  32.614 -  document model of the current buffer.  This is occasionally useful
  32.615 -  for informative purposes, but the amount of displayed information
  32.616 -  might cause problems for large buffers, both for the human and the
  32.617 -  machine.
  32.618 +  Moreover, the special SideKick parser \<^verbatim>\<open>isabelle-markup\<close> provides access to
  32.619 +  the full (uninterpreted) markup tree of the PIDE document model of the
  32.620 +  current buffer. This is occasionally useful for informative purposes, but
  32.621 +  the amount of displayed information might cause problems for large buffers,
  32.622 +  both for the human and the machine.
  32.623  \<close>
  32.624  
  32.625  
  32.626  section \<open>Scala console \label{sec:scala-console}\<close>
  32.627  
  32.628  text \<open>
  32.629 -  The \<^emph>\<open>Console\<close> plugin manages various shells (command interpreters),
  32.630 -  e.g.\ \<^emph>\<open>BeanShell\<close>, which is the official jEdit scripting language, and
  32.631 -  the cross-platform \<^emph>\<open>System\<close> shell. Thus the console provides similar
  32.632 -  functionality than the Emacs buffers \<^verbatim>\<open>*scratch*\<close> and
  32.633 -  \<^verbatim>\<open>*shell*\<close>.
  32.634 +  The \<^emph>\<open>Console\<close> plugin manages various shells (command interpreters), e.g.\
  32.635 +  \<^emph>\<open>BeanShell\<close>, which is the official jEdit scripting language, and the
  32.636 +  cross-platform \<^emph>\<open>System\<close> shell. Thus the console provides similar
  32.637 +  functionality than the Emacs buffers \<^verbatim>\<open>*scratch*\<close> and \<^verbatim>\<open>*shell*\<close>.
  32.638  
  32.639 -  Isabelle/jEdit extends the repertoire of the console by \<^emph>\<open>Scala\<close>, which
  32.640 -  is the regular Scala toplevel loop running inside the same JVM process as
  32.641 +  Isabelle/jEdit extends the repertoire of the console by \<^emph>\<open>Scala\<close>, which is
  32.642 +  the regular Scala toplevel loop running inside the same JVM process as
  32.643    Isabelle/jEdit itself. This means the Scala command interpreter has access
  32.644    to the JVM name space and state of the running Prover IDE application. The
  32.645    default environment imports the full content of packages \<^verbatim>\<open>isabelle\<close> and
  32.646    \<^verbatim>\<open>isabelle.jedit\<close>.
  32.647  
  32.648 -  For example, \<^verbatim>\<open>PIDE\<close> refers to the Isabelle/jEdit plugin object,
  32.649 -  and \<^verbatim>\<open>view\<close> to the current editor view of jEdit. The Scala
  32.650 -  expression \<^verbatim>\<open>PIDE.snapshot(view)\<close> makes a PIDE document snapshot
  32.651 -  of the current buffer within the current editor view.
  32.652 +  For example, \<^verbatim>\<open>PIDE\<close> refers to the Isabelle/jEdit plugin object, and \<^verbatim>\<open>view\<close>
  32.653 +  to the current editor view of jEdit. The Scala expression
  32.654 +  \<^verbatim>\<open>PIDE.snapshot(view)\<close> makes a PIDE document snapshot of the current buffer
  32.655 +  within the current editor view.
  32.656  
  32.657    This helps to explore Isabelle/Scala functionality interactively. Some care
  32.658    is required to avoid interference with the internals of the running
  32.659 @@ -649,10 +634,10 @@
  32.660    File specifications in jEdit follow various formats and conventions
  32.661    according to \<^emph>\<open>Virtual File Systems\<close>, which may be also provided by
  32.662    additional plugins. This allows to access remote files via the \<^verbatim>\<open>http:\<close>
  32.663 -  protocol prefix, for example. Isabelle/jEdit attempts to work with
  32.664 -  the file-system model of jEdit as far as possible. In particular, theory
  32.665 -  sources are passed directly from the editor to the prover, without
  32.666 -  indirection via physical files.
  32.667 +  protocol prefix, for example. Isabelle/jEdit attempts to work with the
  32.668 +  file-system model of jEdit as far as possible. In particular, theory sources
  32.669 +  are passed directly from the editor to the prover, without indirection via
  32.670 +  physical files.
  32.671  
  32.672    Despite the flexibility of URLs in jEdit, local files are particularly
  32.673    important and are accessible without protocol prefix. Here the path notation
  32.674 @@ -663,12 +648,11 @@
  32.675  
  32.676    The Java notation for files needs to be distinguished from the one of
  32.677    Isabelle, which uses POSIX notation with forward slashes on \<^emph>\<open>all\<close>
  32.678 -  platforms.\footnote{Isabelle/ML on Windows uses Cygwin file-system access
  32.679 -  and Unix-style path notation.} Moreover, environment variables from the
  32.680 -  Isabelle process may be used freely, e.g.\ @{file
  32.681 -  "$ISABELLE_HOME/etc/symbols"} or @{file_unchecked "$POLYML_HOME/README"}.
  32.682 -  There are special shortcuts: @{file "~"} for @{file "$USER_HOME"} and @{file
  32.683 -  "~~"} for @{file "$ISABELLE_HOME"}.
  32.684 +  platforms.\<^footnote>\<open>Isabelle/ML on Windows uses Cygwin file-system access and
  32.685 +  Unix-style path notation.\<close> Moreover, environment variables from the Isabelle
  32.686 +  process may be used freely, e.g.\ @{file "$ISABELLE_HOME/etc/symbols"} or
  32.687 +  @{file_unchecked "$POLYML_HOME/README"}. There are special shortcuts: @{file
  32.688 +  "~"} for @{file "$USER_HOME"} and @{file "~~"} for @{file "$ISABELLE_HOME"}.
  32.689  
  32.690    \<^medskip>
  32.691    Since jEdit happens to support environment variables within file
  32.692 @@ -681,20 +665,19 @@
  32.693    (\secref{sec:command-line}).
  32.694  
  32.695    Isabelle/jEdit imitates \<^verbatim>\<open>$ISABELLE_HOME\<close> and \<^verbatim>\<open>$ISABELLE_HOME_USER\<close> within
  32.696 -  the Java process environment, in order to
  32.697 -  allow easy access to these important places from the editor. The file
  32.698 -  browser of jEdit also includes \<^emph>\<open>Favorites\<close> for these two important
  32.699 -  locations.
  32.700 +  the Java process environment, in order to allow easy access to these
  32.701 +  important places from the editor. The file browser of jEdit also includes
  32.702 +  \<^emph>\<open>Favorites\<close> for these two important locations.
  32.703  
  32.704    \<^medskip>
  32.705 -  Path specifications in prover input or output usually include
  32.706 -  formal markup that turns it into a hyperlink (see also
  32.707 -  \secref{sec:tooltips-hyperlinks}). This allows to open the corresponding
  32.708 -  file in the text editor, independently of the path notation.
  32.709 +  Path specifications in prover input or output usually include formal markup
  32.710 +  that turns it into a hyperlink (see also \secref{sec:tooltips-hyperlinks}).
  32.711 +  This allows to open the corresponding file in the text editor, independently
  32.712 +  of the path notation.
  32.713  
  32.714    Formally checked paths in prover input are subject to completion
  32.715 -  (\secref{sec:completion}): partial specifications are resolved via
  32.716 -  directory content and possible completions are offered in a popup.
  32.717 +  (\secref{sec:completion}): partial specifications are resolved via directory
  32.718 +  content and possible completions are offered in a popup.
  32.719  \<close>
  32.720  
  32.721  
  32.722 @@ -720,9 +703,9 @@
  32.723  text \<open>
  32.724    As a regular text editor, jEdit maintains a collection of \<^emph>\<open>buffers\<close> to
  32.725    store text files; each buffer may be associated with any number of visible
  32.726 -  \<^emph>\<open>text areas\<close>. Buffers are subject to an \<^emph>\<open>edit mode\<close> that is
  32.727 -  determined from the file name extension. The following modes are treated
  32.728 -  specifically in Isabelle/jEdit:
  32.729 +  \<^emph>\<open>text areas\<close>. Buffers are subject to an \<^emph>\<open>edit mode\<close> that is determined
  32.730 +  from the file name extension. The following modes are treated specifically
  32.731 +  in Isabelle/jEdit:
  32.732  
  32.733    \<^medskip>
  32.734    \begin{tabular}{lll}
  32.735 @@ -734,17 +717,16 @@
  32.736    \<^medskip>
  32.737  
  32.738    All jEdit buffers are automatically added to the PIDE document-model as
  32.739 -  \<^emph>\<open>document nodes\<close>. The overall document structure is defined by the
  32.740 -  theory nodes in two dimensions:
  32.741 +  \<^emph>\<open>document nodes\<close>. The overall document structure is defined by the theory
  32.742 +  nodes in two dimensions:
  32.743  
  32.744 -  \<^enum> via \<^bold>\<open>theory imports\<close> that are specified in the \<^emph>\<open>theory
  32.745 -  header\<close> using concrete syntax of the @{command_ref theory} command
  32.746 -  @{cite "isabelle-isar-ref"};
  32.747 +    \<^enum> via \<^bold>\<open>theory imports\<close> that are specified in the \<^emph>\<open>theory header\<close> using
  32.748 +    concrete syntax of the @{command_ref theory} command @{cite
  32.749 +    "isabelle-isar-ref"};
  32.750  
  32.751 -  \<^enum> via \<^bold>\<open>auxiliary files\<close> that are loaded into a theory by special
  32.752 -  \<^emph>\<open>load commands\<close>, notably @{command_ref ML_file} and @{command_ref
  32.753 -  SML_file} @{cite "isabelle-isar-ref"}.
  32.754 -
  32.755 +    \<^enum> via \<^bold>\<open>auxiliary files\<close> that are loaded into a theory by special \<^emph>\<open>load
  32.756 +    commands\<close>, notably @{command_ref ML_file} and @{command_ref SML_file}
  32.757 +    @{cite "isabelle-isar-ref"}.
  32.758  
  32.759    In any case, source files are managed by the PIDE infrastructure: the
  32.760    physical file-system only plays a subordinate role. The relevant version of
  32.761 @@ -756,12 +738,12 @@
  32.762  subsection \<open>Theories \label{sec:theories}\<close>
  32.763  
  32.764  text \<open>
  32.765 -  The \<^emph>\<open>Theories\<close> panel (see also \figref{fig:theories}) provides an
  32.766 -  overview of the status of continuous checking of theory nodes within the
  32.767 -  document model. Unlike batch sessions of @{tool build} @{cite
  32.768 -  "isabelle-system"}, theory nodes are identified by full path names; this allows
  32.769 -  to work with multiple (disjoint) Isabelle sessions simultaneously within the
  32.770 -  same editor session.
  32.771 +  The \<^emph>\<open>Theories\<close> panel (see also \figref{fig:theories}) provides an overview
  32.772 +  of the status of continuous checking of theory nodes within the document
  32.773 +  model. Unlike batch sessions of @{tool build} @{cite "isabelle-system"},
  32.774 +  theory nodes are identified by full path names; this allows to work with
  32.775 +  multiple (disjoint) Isabelle sessions simultaneously within the same editor
  32.776 +  session.
  32.777  
  32.778    \begin{figure}[htb]
  32.779    \begin{center}
  32.780 @@ -780,38 +762,36 @@
  32.781    @{system_option jedit_auto_load}.
  32.782  
  32.783    \<^medskip>
  32.784 -  The visible \<^emph>\<open>perspective\<close> of Isabelle/jEdit is defined by the
  32.785 -  collective view on theory buffers via open text areas. The perspective is
  32.786 -  taken as a hint for document processing: the prover ensures that those parts
  32.787 -  of a theory where the user is looking are checked, while other parts that
  32.788 -  are presently not required are ignored. The perspective is changed by
  32.789 -  opening or closing text area windows, or scrolling within a window.
  32.790 +  The visible \<^emph>\<open>perspective\<close> of Isabelle/jEdit is defined by the collective
  32.791 +  view on theory buffers via open text areas. The perspective is taken as a
  32.792 +  hint for document processing: the prover ensures that those parts of a
  32.793 +  theory where the user is looking are checked, while other parts that are
  32.794 +  presently not required are ignored. The perspective is changed by opening or
  32.795 +  closing text area windows, or scrolling within a window.
  32.796  
  32.797 -  The \<^emph>\<open>Theories\<close> panel provides some further options to influence
  32.798 -  the process of continuous checking: it may be switched off globally
  32.799 -  to restrict the prover to superficial processing of command syntax.
  32.800 -  It is also possible to indicate theory nodes as \<^emph>\<open>required\<close> for
  32.801 -  continuous checking: this means such nodes and all their imports are
  32.802 -  always processed independently of the visibility status (if
  32.803 -  continuous checking is enabled).  Big theory libraries that are
  32.804 -  marked as required can have significant impact on performance,
  32.805 +  The \<^emph>\<open>Theories\<close> panel provides some further options to influence the process
  32.806 +  of continuous checking: it may be switched off globally to restrict the
  32.807 +  prover to superficial processing of command syntax. It is also possible to
  32.808 +  indicate theory nodes as \<^emph>\<open>required\<close> for continuous checking: this means
  32.809 +  such nodes and all their imports are always processed independently of the
  32.810 +  visibility status (if continuous checking is enabled). Big theory libraries
  32.811 +  that are marked as required can have significant impact on performance,
  32.812    though.
  32.813  
  32.814    \<^medskip>
  32.815 -  Formal markup of checked theory content is turned into GUI
  32.816 -  rendering, based on a standard repertoire known from IDEs for programming
  32.817 -  languages: colors, icons, highlighting, squiggly underlines, tooltips,
  32.818 -  hyperlinks etc. For outer syntax of Isabelle/Isar there is some traditional
  32.819 -  syntax-highlighting via static keywords and tokenization within the editor;
  32.820 -  this buffer syntax is determined from theory imports. In contrast, the
  32.821 -  painting of inner syntax (term language etc.)\ uses semantic information
  32.822 -  that is reported dynamically from the logical context. Thus the prover can
  32.823 -  provide additional markup to help the user to understand the meaning of
  32.824 -  formal text, and to produce more text with some add-on tools (e.g.\
  32.825 -  information messages with \<^emph>\<open>sendback\<close> markup by automated provers or
  32.826 -  disprovers in the background).
  32.827 +  Formal markup of checked theory content is turned into GUI rendering, based
  32.828 +  on a standard repertoire known from IDEs for programming languages: colors,
  32.829 +  icons, highlighting, squiggly underlines, tooltips, hyperlinks etc. For
  32.830 +  outer syntax of Isabelle/Isar there is some traditional syntax-highlighting
  32.831 +  via static keywords and tokenization within the editor; this buffer syntax
  32.832 +  is determined from theory imports. In contrast, the painting of inner syntax
  32.833 +  (term language etc.)\ uses semantic information that is reported dynamically
  32.834 +  from the logical context. Thus the prover can provide additional markup to
  32.835 +  help the user to understand the meaning of formal text, and to produce more
  32.836 +  text with some add-on tools (e.g.\ information messages with \<^emph>\<open>sendback\<close>
  32.837 +  markup by automated provers or disprovers in the background).
  32.838 +\<close>
  32.839  
  32.840 -\<close>
  32.841  
  32.842  subsection \<open>Auxiliary files \label{sec:aux-files}\<close>
  32.843  
  32.844 @@ -826,14 +806,13 @@
  32.845    treated as changes of the corresponding load command.
  32.846  
  32.847    \<^medskip>
  32.848 -  As a concession to the massive amount of ML files in Isabelle/HOL
  32.849 -  itself, the content of auxiliary files is only added to the PIDE
  32.850 -  document-model on demand, the first time when opened explicitly in the
  32.851 -  editor. There are further tricks to manage markup of ML files, such that
  32.852 -  Isabelle/HOL may be edited conveniently in the Prover IDE on small machines
  32.853 -  with only 8\,GB of main memory. Using \<^verbatim>\<open>Pure\<close> as logic session
  32.854 -  image, the exploration may start at the top @{file
  32.855 -  "$ISABELLE_HOME/src/HOL/Main.thy"} or the bottom @{file
  32.856 +  As a concession to the massive amount of ML files in Isabelle/HOL itself,
  32.857 +  the content of auxiliary files is only added to the PIDE document-model on
  32.858 +  demand, the first time when opened explicitly in the editor. There are
  32.859 +  further tricks to manage markup of ML files, such that Isabelle/HOL may be
  32.860 +  edited conveniently in the Prover IDE on small machines with only 8\,GB of
  32.861 +  main memory. Using \<^verbatim>\<open>Pure\<close> as logic session image, the exploration may start
  32.862 +  at the top @{file "$ISABELLE_HOME/src/HOL/Main.thy"} or the bottom @{file
  32.863    "$ISABELLE_HOME/src/HOL/HOL.thy"}, for example.
  32.864  
  32.865    Initially, before an auxiliary file is opened in the editor, the prover
  32.866 @@ -853,30 +832,30 @@
  32.867    morally unsupported and might lead to confusion.
  32.868  
  32.869    \<^medskip>
  32.870 -  Output that refers to an auxiliary file is combined with that of
  32.871 -  the corresponding load command, and shown whenever the file or the command
  32.872 -  are active (see also \secref{sec:output}).
  32.873 +  Output that refers to an auxiliary file is combined with that of the
  32.874 +  corresponding load command, and shown whenever the file or the command are
  32.875 +  active (see also \secref{sec:output}).
  32.876  
  32.877    Warnings, errors, and other useful markup is attached directly to the
  32.878    positions in the auxiliary file buffer, in the manner of other well-known
  32.879    IDEs. By using the load command @{command SML_file} as explained in @{file
  32.880    "$ISABELLE_HOME/src/Tools/SML/Examples.thy"}, Isabelle/jEdit may be used as
  32.881    fully-featured IDE for Standard ML, independently of theory or proof
  32.882 -  development: the required theory merely serves as some kind of project
  32.883 -  file for a collection of SML source modules.
  32.884 +  development: the required theory merely serves as some kind of project file
  32.885 +  for a collection of SML source modules.
  32.886  \<close>
  32.887  
  32.888  
  32.889  section \<open>Output \label{sec:output}\<close>
  32.890  
  32.891  text \<open>
  32.892 -  Prover output consists of \<^emph>\<open>markup\<close> and \<^emph>\<open>messages\<close>. Both are
  32.893 -  directly attached to the corresponding positions in the original source
  32.894 -  text, and visualized in the text area, e.g.\ as text colours for free and
  32.895 -  bound variables, or as squiggly underlines for warnings, errors etc.\ (see
  32.896 -  also \figref{fig:output}). In the latter case, the corresponding messages
  32.897 -  are shown by hovering with the mouse over the highlighted text --- although
  32.898 -  in many situations the user should already get some clue by looking at the
  32.899 +  Prover output consists of \<^emph>\<open>markup\<close> and \<^emph>\<open>messages\<close>. Both are directly
  32.900 +  attached to the corresponding positions in the original source text, and
  32.901 +  visualized in the text area, e.g.\ as text colours for free and bound
  32.902 +  variables, or as squiggly underlines for warnings, errors etc.\ (see also
  32.903 +  \figref{fig:output}). In the latter case, the corresponding messages are
  32.904 +  shown by hovering with the mouse over the highlighted text --- although in
  32.905 +  many situations the user should already get some clue by looking at the
  32.906    position of the text highlighting, without the text itself.
  32.907  
  32.908    \begin{figure}[htb]
  32.909 @@ -888,11 +867,10 @@
  32.910    \label{fig:output}
  32.911    \end{figure}
  32.912  
  32.913 -  The ``gutter area'' on the left-hand-side of the text area uses
  32.914 -  icons to provide a summary of the messages within the adjacent
  32.915 -  line of text.  Message priorities are used to prefer errors over
  32.916 -  warnings, warnings over information messages, but plain output is
  32.917 -  ignored.
  32.918 +  The ``gutter area'' on the left-hand-side of the text area uses icons to
  32.919 +  provide a summary of the messages within the adjacent line of text. Message
  32.920 +  priorities are used to prefer errors over warnings, warnings over
  32.921 +  information messages, but plain output is ignored.
  32.922  
  32.923    The ``overview area'' on the right-hand-side of the text area uses similar
  32.924    information to paint small rectangles for the overall status of the whole
  32.925 @@ -900,16 +878,14 @@
  32.926    the given window height. Mouse clicks on the overview area position the
  32.927    cursor approximately to the corresponding line of text in the buffer.
  32.928  
  32.929 -  Another course-grained overview is provided by the \<^emph>\<open>Theories\<close>
  32.930 -  panel, but without direct correspondence to text positions.  A
  32.931 -  double-click on one of the theory entries with their status overview
  32.932 -  opens the corresponding text buffer, without changing the cursor
  32.933 -  position.
  32.934 +  Another course-grained overview is provided by the \<^emph>\<open>Theories\<close> panel, but
  32.935 +  without direct correspondence to text positions. A double-click on one of
  32.936 +  the theory entries with their status overview opens the corresponding text
  32.937 +  buffer, without changing the cursor position.
  32.938  
  32.939    \<^medskip>
  32.940 -  In addition, the \<^emph>\<open>Output\<close> panel displays prover
  32.941 -  messages that correspond to a given command, within a separate
  32.942 -  window.
  32.943 +  In addition, the \<^emph>\<open>Output\<close> panel displays prover messages that correspond to
  32.944 +  a given command, within a separate window.
  32.945  
  32.946    The cursor position in the presently active text area determines the prover
  32.947    command whose cumulative message output is appended and shown in that window
  32.948 @@ -925,36 +901,34 @@
  32.949    possible to do meaningful proof editing within the primary text area and its
  32.950    markup, while using secondary output windows only rarely.
  32.951  
  32.952 -  The main purpose of the output window is to ``debug'' unclear
  32.953 -  situations by inspecting internal state of the prover.\footnote{In
  32.954 -  that sense, unstructured tactic scripts depend on continuous
  32.955 -  debugging with internal state inspection.} Consequently, some
  32.956 -  special messages for \<^emph>\<open>tracing\<close> or \<^emph>\<open>proof state\<close> only
  32.957 +  The main purpose of the output window is to ``debug'' unclear situations by
  32.958 +  inspecting internal state of the prover.\<^footnote>\<open>In that sense, unstructured tactic
  32.959 +  scripts depend on continuous debugging with internal state inspection.\<close>
  32.960 +  Consequently, some special messages for \<^emph>\<open>tracing\<close> or \<^emph>\<open>proof state\<close> only
  32.961    appear here, and are not attached to the original source.
  32.962  
  32.963    \<^medskip>
  32.964 -  In any case, prover messages also contain markup that may
  32.965 -  be explored recursively via tooltips or hyperlinks (see
  32.966 -  \secref{sec:tooltips-hyperlinks}), or clicked directly to initiate
  32.967 -  certain actions (see \secref{sec:auto-tools} and
  32.968 -  \secref{sec:sledgehammer}).\<close>
  32.969 +  In any case, prover messages also contain markup that may be explored
  32.970 +  recursively via tooltips or hyperlinks (see
  32.971 +  \secref{sec:tooltips-hyperlinks}), or clicked directly to initiate certain
  32.972 +  actions (see \secref{sec:auto-tools} and \secref{sec:sledgehammer}).
  32.973 +\<close>
  32.974  
  32.975  
  32.976  section \<open>Query \label{sec:query}\<close>
  32.977  
  32.978  text \<open>
  32.979 -  The \<^emph>\<open>Query\<close> panel provides various GUI forms to request extra
  32.980 -  information from the prover. In old times the user would have issued some
  32.981 -  diagnostic command like @{command find_theorems} and inspected its output,
  32.982 -  but this is now integrated into the Prover IDE.
  32.983 +  The \<^emph>\<open>Query\<close> panel provides various GUI forms to request extra information
  32.984 +  from the prover. In old times the user would have issued some diagnostic
  32.985 +  command like @{command find_theorems} and inspected its output, but this is
  32.986 +  now integrated into the Prover IDE.
  32.987  
  32.988 -  A \<^emph>\<open>Query\<close> window provides some input fields and buttons for a
  32.989 -  particular query command, with output in a dedicated text area. There are
  32.990 -  various query modes: \<^emph>\<open>Find Theorems\<close>, \<^emph>\<open>Find Constants\<close>,
  32.991 -  \<^emph>\<open>Print Context\<close>, e.g.\ see \figref{fig:query}. As usual in jEdit,
  32.992 -  multiple \<^emph>\<open>Query\<close> windows may be active at the same time: any number of
  32.993 -  floating instances, but at most one docked instance (which is used by
  32.994 -  default).
  32.995 +  A \<^emph>\<open>Query\<close> window provides some input fields and buttons for a particular
  32.996 +  query command, with output in a dedicated text area. There are various query
  32.997 +  modes: \<^emph>\<open>Find Theorems\<close>, \<^emph>\<open>Find Constants\<close>, \<^emph>\<open>Print Context\<close>, e.g.\ see
  32.998 +  \figref{fig:query}. As usual in jEdit, multiple \<^emph>\<open>Query\<close> windows may be
  32.999 +  active at the same time: any number of floating instances, but at most one
 32.1000 +  docked instance (which is used by default).
 32.1001  
 32.1002    \begin{figure}[htb]
 32.1003    \begin{center}
 32.1004 @@ -967,20 +941,19 @@
 32.1005    \<^medskip>
 32.1006    The following GUI elements are common to all query modes:
 32.1007  
 32.1008 -  \<^item> The spinning wheel provides feedback about the status of a pending
 32.1009 -  query wrt.\ the evaluation of its context and its own operation.
 32.1010 +    \<^item> The spinning wheel provides feedback about the status of a pending query
 32.1011 +    wrt.\ the evaluation of its context and its own operation.
 32.1012  
 32.1013 -  \<^item> The \<^emph>\<open>Apply\<close> button attaches a fresh query invocation to the
 32.1014 -  current context of the command where the cursor is pointing in the text.
 32.1015 +    \<^item> The \<^emph>\<open>Apply\<close> button attaches a fresh query invocation to the current
 32.1016 +    context of the command where the cursor is pointing in the text.
 32.1017  
 32.1018 -  \<^item> The \<^emph>\<open>Search\<close> field allows to highlight query output according to
 32.1019 -  some regular expression, in the notation that is commonly used on the Java
 32.1020 -  platform.\footnote{@{url
 32.1021 -  "http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html"}}
 32.1022 -  This may serve as an additional visual filter of the result.
 32.1023 +    \<^item> The \<^emph>\<open>Search\<close> field allows to highlight query output according to some
 32.1024 +    regular expression, in the notation that is commonly used on the Java
 32.1025 +    platform.\<^footnote>\<open>@{url
 32.1026 +    "https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html"}\<close>
 32.1027 +    This may serve as an additional visual filter of the result.
 32.1028  
 32.1029 -  \<^item> The \<^emph>\<open>Zoom\<close> box controls the font size of the output area.
 32.1030 -
 32.1031 +    \<^item> The \<^emph>\<open>Zoom\<close> box controls the font size of the output area.
 32.1032  
 32.1033    All query operations are asynchronous: there is no need to wait for the
 32.1034    evaluation of the document for the query context, nor for the query
 32.1035 @@ -994,26 +967,26 @@
 32.1036  subsection \<open>Find theorems\<close>
 32.1037  
 32.1038  text \<open>
 32.1039 -  The \<^emph>\<open>Query\<close> panel in \<^emph>\<open>Find Theorems\<close> mode retrieves facts from the
 32.1040 -  theory or proof context matching all of given criteria in the \<^emph>\<open>Find\<close>
 32.1041 -  text field. A single criterium has the following syntax:
 32.1042 +  The \<^emph>\<open>Query\<close> panel in \<^emph>\<open>Find Theorems\<close> mode retrieves facts from the theory
 32.1043 +  or proof context matching all of given criteria in the \<^emph>\<open>Find\<close> text field. A
 32.1044 +  single criterium has the following syntax:
 32.1045  
 32.1046    @{rail \<open>
 32.1047      ('-'?) ('name' ':' @{syntax nameref} | 'intro' | 'elim' | 'dest' |
 32.1048        'solves' | 'simp' ':' @{syntax term} | @{syntax term})
 32.1049    \<close>}
 32.1050  
 32.1051 -  See also the Isar command @{command_ref find_theorems} in
 32.1052 -  @{cite "isabelle-isar-ref"}.
 32.1053 +  See also the Isar command @{command_ref find_theorems} in @{cite
 32.1054 +  "isabelle-isar-ref"}.
 32.1055  \<close>
 32.1056  
 32.1057  
 32.1058  subsection \<open>Find constants\<close>
 32.1059  
 32.1060  text \<open>
 32.1061 -  The \<^emph>\<open>Query\<close> panel in \<^emph>\<open>Find Constants\<close> mode prints all constants
 32.1062 -  whose type meets all of the given criteria in the \<^emph>\<open>Find\<close> text field.
 32.1063 -  A single criterium has the following syntax:
 32.1064 +  The \<^emph>\<open>Query\<close> panel in \<^emph>\<open>Find Constants\<close> mode prints all constants whose type
 32.1065 +  meets all of the given criteria in the \<^emph>\<open>Find\<close> text field. A single
 32.1066 +  criterium has the following syntax:
 32.1067  
 32.1068    @{rail \<open>
 32.1069      ('-'?)
 32.1070 @@ -1028,8 +1001,8 @@
 32.1071  subsection \<open>Print context\<close>
 32.1072  
 32.1073  text \<open>
 32.1074 -  The \<^emph>\<open>Query\<close> panel in \<^emph>\<open>Print Context\<close> mode prints information from
 32.1075 -  the theory or proof context, or proof state. See also the Isar commands
 32.1076 +  The \<^emph>\<open>Query\<close> panel in \<^emph>\<open>Print Context\<close> mode prints information from the
 32.1077 +  theory or proof context, or proof state. See also the Isar commands
 32.1078    @{command_ref print_context}, @{command_ref print_cases}, @{command_ref
 32.1079    print_term_bindings}, @{command_ref print_theorems}, @{command_ref
 32.1080    print_state} described in @{cite "isabelle-isar-ref"}.
 32.1081 @@ -1040,12 +1013,11 @@
 32.1082  
 32.1083  text \<open>
 32.1084    Formally processed text (prover input or output) contains rich markup
 32.1085 -  information that can be explored further by using the \<^verbatim>\<open>CONTROL\<close>
 32.1086 -  modifier key on Linux and Windows, or \<^verbatim>\<open>COMMAND\<close> on Mac OS X.
 32.1087 -  Hovering with the mouse while the modifier is pressed reveals a
 32.1088 -  \<^emph>\<open>tooltip\<close> (grey box over the text with a yellow popup) and/or a
 32.1089 -  \<^emph>\<open>hyperlink\<close> (black rectangle over the text with change of mouse
 32.1090 -  pointer); see also \figref{fig:tooltip}.
 32.1091 +  information that can be explored further by using the \<^verbatim>\<open>CONTROL\<close> modifier
 32.1092 +  key on Linux and Windows, or \<^verbatim>\<open>COMMAND\<close> on Mac OS X. Hovering with the mouse
 32.1093 +  while the modifier is pressed reveals a \<^emph>\<open>tooltip\<close> (grey box over the text
 32.1094 +  with a yellow popup) and/or a \<^emph>\<open>hyperlink\<close> (black rectangle over the text
 32.1095 +  with change of mouse pointer); see also \figref{fig:tooltip}.
 32.1096  
 32.1097    \begin{figure}[htb]
 32.1098    \begin{center}
 32.1099 @@ -1055,9 +1027,9 @@
 32.1100    \label{fig:tooltip}
 32.1101    \end{figure}
 32.1102  
 32.1103 -  Tooltip popups use the same rendering mechanisms as the main text
 32.1104 -  area, and further tooltips and/or hyperlinks may be exposed
 32.1105 -  recursively by the same mechanism; see \figref{fig:nested-tooltips}.
 32.1106 +  Tooltip popups use the same rendering mechanisms as the main text area, and
 32.1107 +  further tooltips and/or hyperlinks may be exposed recursively by the same
 32.1108 +  mechanism; see \figref{fig:nested-tooltips}.
 32.1109  
 32.1110    \begin{figure}[htb]
 32.1111    \begin{center}
 32.1112 @@ -1067,25 +1039,24 @@
 32.1113    \label{fig:nested-tooltips}
 32.1114    \end{figure}
 32.1115  
 32.1116 -  The tooltip popup window provides some controls to \<^emph>\<open>close\<close> or
 32.1117 -  \<^emph>\<open>detach\<close> the window, turning it into a separate \<^emph>\<open>Info\<close>
 32.1118 -  window managed by jEdit.  The \<^verbatim>\<open>ESCAPE\<close> key closes
 32.1119 -  \<^emph>\<open>all\<close> popups, which is particularly relevant when nested
 32.1120 -  tooltips are stacking up.
 32.1121 +  The tooltip popup window provides some controls to \<^emph>\<open>close\<close> or \<^emph>\<open>detach\<close> the
 32.1122 +  window, turning it into a separate \<^emph>\<open>Info\<close> window managed by jEdit. The
 32.1123 +  \<^verbatim>\<open>ESCAPE\<close> key closes \<^emph>\<open>all\<close> popups, which is particularly relevant when
 32.1124 +  nested tooltips are stacking up.
 32.1125  
 32.1126    \<^medskip>
 32.1127 -  A black rectangle in the text indicates a hyperlink that may be
 32.1128 -  followed by a mouse click (while the \<^verbatim>\<open>CONTROL\<close> or \<^verbatim>\<open>COMMAND\<close> modifier
 32.1129 -  key is still pressed). Such jumps to other text locations
 32.1130 -  are recorded by the \<^emph>\<open>Navigator\<close> plugin, which is bundled with
 32.1131 -  Isabelle/jEdit and enabled by default, including navigation arrows in the
 32.1132 -  main jEdit toolbar.
 32.1133 +  A black rectangle in the text indicates a hyperlink that may be followed by
 32.1134 +  a mouse click (while the \<^verbatim>\<open>CONTROL\<close> or \<^verbatim>\<open>COMMAND\<close> modifier key is still
 32.1135 +  pressed). Such jumps to other text locations are recorded by the
 32.1136 +  \<^emph>\<open>Navigator\<close> plugin, which is bundled with Isabelle/jEdit and enabled by
 32.1137 +  default, including navigation arrows in the main jEdit toolbar.
 32.1138  
 32.1139 -  Also note that the link target may be a file that is itself not
 32.1140 -  subject to formal document processing of the editor session and thus
 32.1141 -  prevents further exploration: the chain of hyperlinks may end in
 32.1142 -  some source file of the underlying logic image, or within the
 32.1143 -  ML bootstrap sources of Isabelle/Pure.\<close>
 32.1144 +  Also note that the link target may be a file that is itself not subject to
 32.1145 +  formal document processing of the editor session and thus prevents further
 32.1146 +  exploration: the chain of hyperlinks may end in some source file of the
 32.1147 +  underlying logic image, or within the ML bootstrap sources of
 32.1148 +  Isabelle/Pure.
 32.1149 +\<close>
 32.1150  
 32.1151  
 32.1152  section \<open>Completion \label{sec:completion}\<close>
 32.1153 @@ -1100,16 +1071,16 @@
 32.1154  
 32.1155    \<^medskip>
 32.1156    \<^emph>\<open>Explicit completion\<close> is triggered by the action @{action_ref
 32.1157 -  "isabelle.complete"}, which is bound to the keyboard shortcut \<^verbatim>\<open>C+b\<close>,
 32.1158 -  and thus overrides the jEdit default for @{action_ref "complete-word"}.
 32.1159 +  "isabelle.complete"}, which is bound to the keyboard shortcut \<^verbatim>\<open>C+b\<close>, and
 32.1160 +  thus overrides the jEdit default for @{action_ref "complete-word"}.
 32.1161  
 32.1162 -  \<^emph>\<open>Implicit completion\<close> hooks into the regular keyboard input stream of
 32.1163 -  the editor, with some event filtering and optional delays.
 32.1164 +  \<^emph>\<open>Implicit completion\<close> hooks into the regular keyboard input stream of the
 32.1165 +  editor, with some event filtering and optional delays.
 32.1166  
 32.1167    \<^medskip>
 32.1168 -  Completion options may be configured in \<^emph>\<open>Plugin Options~/
 32.1169 -  Isabelle~/ General~/ Completion\<close>. These are explained in further detail
 32.1170 -  below, whenever relevant. There is also a summary of options in
 32.1171 +  Completion options may be configured in \<^emph>\<open>Plugin Options~/ Isabelle~/
 32.1172 +  General~/ Completion\<close>. These are explained in further detail below, whenever
 32.1173 +  relevant. There is also a summary of options in
 32.1174    \secref{sec:completion-options}.
 32.1175  
 32.1176    The asynchronous nature of PIDE interaction means that information from the
 32.1177 @@ -1132,19 +1103,17 @@
 32.1178    kinds and purposes. The completion mechanism supports this by the following
 32.1179    built-in templates:
 32.1180  
 32.1181 -  \<^descr> \<^verbatim>\<open>`\<close> (single ASCII back-quote) supports \<^emph>\<open>quotations\<close>
 32.1182 -  via text cartouches. There are three selections, which are always presented
 32.1183 -  in the same order and do not depend on any context information. The default
 32.1184 -  choice produces a template ``\<open>\<open>\<box>\<close>\<close>'', where the box indicates the
 32.1185 -  cursor position after insertion; the other choices help to repair the block
 32.1186 -  structure of unbalanced text cartouches.
 32.1187 +    \<^descr> \<^verbatim>\<open>`\<close> (single ASCII back-quote) supports \<^emph>\<open>quotations\<close> via text
 32.1188 +    cartouches. There are three selections, which are always presented in the
 32.1189 +    same order and do not depend on any context information. The default
 32.1190 +    choice produces a template ``\<open>\<open>\<box>\<close>\<close>'', where the box indicates the cursor
 32.1191 +    position after insertion; the other choices help to repair the block
 32.1192 +    structure of unbalanced text cartouches.
 32.1193  
 32.1194 -  \<^descr> \<^verbatim>\<open>@{\<close> is completed to the template ``\<open>@{\<box>}\<close>'',
 32.1195 -  where the box indicates the cursor position after insertion. Here it is
 32.1196 -  convenient to use the wildcard ``\<^verbatim>\<open>__\<close>'' or a more specific name
 32.1197 -  prefix to let semantic completion of name-space entries propose
 32.1198 -  antiquotation names.
 32.1199 -
 32.1200 +    \<^descr> \<^verbatim>\<open>@{\<close> is completed to the template ``\<open>@{\<box>}\<close>'', where the box indicates
 32.1201 +    the cursor position after insertion. Here it is convenient to use the
 32.1202 +    wildcard ``\<^verbatim>\<open>__\<close>'' or a more specific name prefix to let semantic
 32.1203 +    completion of name-space entries propose antiquotation names.
 32.1204  
 32.1205    With some practice, input of quoted sub-languages and antiquotations of
 32.1206    embedded languages should work fluently. Note that national keyboard layouts
 32.1207 @@ -1193,10 +1162,9 @@
 32.1208    When inserted into the text, the above examples all produce the same Unicode
 32.1209    rendering \<open>\<forall>\<close> of the underlying symbol \<^verbatim>\<open>\<forall>\<close>.
 32.1210  
 32.1211 -  A symbol abbreviation that is a plain word, like \<^verbatim>\<open>ALL\<close>, is
 32.1212 -  treated like a syntax keyword. Non-word abbreviations like \<^verbatim>\<open>-->\<close>
 32.1213 -  are inserted more aggressively, except for single-character abbreviations
 32.1214 -  like \<^verbatim>\<open>!\<close> above.
 32.1215 +  A symbol abbreviation that is a plain word, like \<^verbatim>\<open>ALL\<close>, is treated like a
 32.1216 +  syntax keyword. Non-word abbreviations like \<^verbatim>\<open>-->\<close> are inserted more
 32.1217 +  aggressively, except for single-character abbreviations like \<^verbatim>\<open>!\<close> above.
 32.1218  
 32.1219    \<^medskip>
 32.1220    Symbol completion depends on the semantic language context
 32.1221 @@ -1217,17 +1185,17 @@
 32.1222    @{system_option_ref completion_limit}. The completion mechanism takes this
 32.1223    into account when collecting information on the prover side.
 32.1224  
 32.1225 -  Already recognized names are \<^emph>\<open>not\<close> completed further, but completion
 32.1226 -  may be extended by appending a suffix of underscores. This provokes a failed
 32.1227 +  Already recognized names are \<^emph>\<open>not\<close> completed further, but completion may be
 32.1228 +  extended by appending a suffix of underscores. This provokes a failed
 32.1229    lookup, and another completion attempt while ignoring the underscores. For
 32.1230 -  example, in a name space where \<^verbatim>\<open>foo\<close> and \<^verbatim>\<open>foobar\<close>
 32.1231 -  are known, the input \<^verbatim>\<open>foo\<close> remains unchanged, but \<^verbatim>\<open>foo_\<close> may be completed
 32.1232 -  to \<^verbatim>\<open>foo\<close> or \<^verbatim>\<open>foobar\<close>.
 32.1233 +  example, in a name space where \<^verbatim>\<open>foo\<close> and \<^verbatim>\<open>foobar\<close> are known, the input
 32.1234 +  \<^verbatim>\<open>foo\<close> remains unchanged, but \<^verbatim>\<open>foo_\<close> may be completed to \<^verbatim>\<open>foo\<close> or
 32.1235 +  \<^verbatim>\<open>foobar\<close>.
 32.1236  
 32.1237 -  The special identifier ``\<^verbatim>\<open>__\<close>'' serves as a wild-card for
 32.1238 -  arbitrary completion: it exposes the name-space content to the completion
 32.1239 -  mechanism (truncated according to @{system_option completion_limit}). This
 32.1240 -  is occasionally useful to explore an unknown name-space, e.g.\ in some
 32.1241 +  The special identifier ``\<^verbatim>\<open>__\<close>'' serves as a wild-card for arbitrary
 32.1242 +  completion: it exposes the name-space content to the completion mechanism
 32.1243 +  (truncated according to @{system_option completion_limit}). This is
 32.1244 +  occasionally useful to explore an unknown name-space, e.g.\ in some
 32.1245    template.
 32.1246  \<close>
 32.1247  
 32.1248 @@ -1239,9 +1207,9 @@
 32.1249    source text, e.g.\ for the argument of a load command
 32.1250    (\secref{sec:aux-files}), the completion mechanism explores the directory
 32.1251    content and offers the result as completion popup. Relative path
 32.1252 -  specifications are understood wrt.\ the \<^emph>\<open>master directory\<close> of the
 32.1253 -  document node (\secref{sec:buffer-node}) of the enclosing editor buffer;
 32.1254 -  this requires a proper theory, not an auxiliary file.
 32.1255 +  specifications are understood wrt.\ the \<^emph>\<open>master directory\<close> of the document
 32.1256 +  node (\secref{sec:buffer-node}) of the enclosing editor buffer; this
 32.1257 +  requires a proper theory, not an auxiliary file.
 32.1258  
 32.1259    A suffix of slashes may be used to continue the exploration of an already
 32.1260    recognized directory name.
 32.1261 @@ -1274,10 +1242,10 @@
 32.1262    default keyboard shortcut \<^verbatim>\<open>C+b\<close>.
 32.1263  
 32.1264    \<^medskip>
 32.1265 -  Dictionary lookup uses some educated guesses about lower-case,
 32.1266 -  upper-case, and capitalized words. This is oriented on common use in
 32.1267 -  English, where this aspect is not decisive for proper spelling, in contrast
 32.1268 -  to German, for example.
 32.1269 +  Dictionary lookup uses some educated guesses about lower-case, upper-case,
 32.1270 +  and capitalized words. This is oriented on common use in English, where this
 32.1271 +  aspect is not decisive for proper spelling, in contrast to German, for
 32.1272 +  example.
 32.1273  \<close>
 32.1274  
 32.1275  
 32.1276 @@ -1296,14 +1264,14 @@
 32.1277    symbol completion for ML source, but within ML strings, comments,
 32.1278    antiquotations.
 32.1279  
 32.1280 -  The prover may produce \<^emph>\<open>no completion\<close> markup in exceptional
 32.1281 -  situations, to tell that some language keywords should be excluded from
 32.1282 -  further completion attempts. For example, \<^verbatim>\<open>:\<close> within accepted
 32.1283 -  Isar syntax looses its meaning as abbreviation for symbol \<open>\<in>\<close>.
 32.1284 +  The prover may produce \<^emph>\<open>no completion\<close> markup in exceptional situations, to
 32.1285 +  tell that some language keywords should be excluded from further completion
 32.1286 +  attempts. For example, \<^verbatim>\<open>:\<close> within accepted Isar syntax looses its meaning
 32.1287 +  as abbreviation for symbol \<open>\<in>\<close>.
 32.1288  
 32.1289    \<^medskip>
 32.1290 -  The completion context is \<^emph>\<open>ignored\<close> for built-in templates and
 32.1291 -  symbols in their explicit form ``\<^verbatim>\<open>\<foobar>\<close>''; see also
 32.1292 +  The completion context is \<^emph>\<open>ignored\<close> for built-in templates and symbols in
 32.1293 +  their explicit form ``\<^verbatim>\<open>\<foobar>\<close>''; see also
 32.1294    \secref{sec:completion-varieties}. This allows to complete within broken
 32.1295    input that escapes its normal semantic context, e.g.\ antiquotations or
 32.1296    string literals in ML, which do not allow arbitrary backslash sequences.
 32.1297 @@ -1317,56 +1285,55 @@
 32.1298    optional delay after keyboard input according to @{system_option
 32.1299    jedit_completion_delay}.
 32.1300  
 32.1301 -  \<^descr>[Explicit completion] works via action @{action_ref
 32.1302 -  "isabelle.complete"} with keyboard shortcut \<^verbatim>\<open>C+b\<close>. This
 32.1303 -  overrides the shortcut for @{action_ref "complete-word"} in jEdit, but it is
 32.1304 -  possible to restore the original jEdit keyboard mapping of @{action
 32.1305 -  "complete-word"} via \<^emph>\<open>Global Options~/ Shortcuts\<close> and invent a
 32.1306 -  different one for @{action "isabelle.complete"}.
 32.1307 +  \<^descr>[Explicit completion] works via action @{action_ref "isabelle.complete"}
 32.1308 +  with keyboard shortcut \<^verbatim>\<open>C+b\<close>. This overrides the shortcut for @{action_ref
 32.1309 +  "complete-word"} in jEdit, but it is possible to restore the original jEdit
 32.1310 +  keyboard mapping of @{action "complete-word"} via \<^emph>\<open>Global Options~/
 32.1311 +  Shortcuts\<close> and invent a different one for @{action "isabelle.complete"}.
 32.1312  
 32.1313    \<^descr>[Explicit spell-checker completion] works via @{action_ref
 32.1314    "isabelle.complete-word"}, which is exposed in the jEdit context menu, if
 32.1315    the mouse points to a word that the spell-checker can complete.
 32.1316  
 32.1317 -  \<^descr>[Implicit completion] works via regular keyboard input of the editor.
 32.1318 -  It depends on further side-conditions:
 32.1319 +  \<^descr>[Implicit completion] works via regular keyboard input of the editor. It
 32.1320 +  depends on further side-conditions:
 32.1321  
 32.1322 -    \<^enum> The system option @{system_option_ref jedit_completion} needs to
 32.1323 -    be enabled (default).
 32.1324 +    \<^enum> The system option @{system_option_ref jedit_completion} needs to be
 32.1325 +    enabled (default).
 32.1326  
 32.1327 -    \<^enum> Completion of syntax keywords requires at least 3 relevant
 32.1328 -    characters in the text.
 32.1329 +    \<^enum> Completion of syntax keywords requires at least 3 relevant characters in
 32.1330 +    the text.
 32.1331  
 32.1332 -    \<^enum> The system option @{system_option_ref jedit_completion_delay}
 32.1333 -    determines an additional delay (0.5 by default), before opening a completion
 32.1334 -    popup.  The delay gives the prover a chance to provide semantic completion
 32.1335 +    \<^enum> The system option @{system_option_ref jedit_completion_delay} determines
 32.1336 +    an additional delay (0.5 by default), before opening a completion popup.
 32.1337 +    The delay gives the prover a chance to provide semantic completion
 32.1338      information, notably the context (\secref{sec:completion-context}).
 32.1339  
 32.1340      \<^enum> The system option @{system_option_ref jedit_completion_immediate}
 32.1341      (enabled by default) controls whether replacement text should be inserted
 32.1342      immediately without popup, regardless of @{system_option
 32.1343 -    jedit_completion_delay}. This aggressive mode of completion is restricted to
 32.1344 -    Isabelle symbols and their abbreviations (\secref{sec:symbols}).
 32.1345 +    jedit_completion_delay}. This aggressive mode of completion is restricted
 32.1346 +    to Isabelle symbols and their abbreviations (\secref{sec:symbols}).
 32.1347  
 32.1348 -    \<^enum> Completion of symbol abbreviations with only one relevant
 32.1349 -    character in the text always enforces an explicit popup,
 32.1350 -    regardless of @{system_option_ref jedit_completion_immediate}.
 32.1351 +    \<^enum> Completion of symbol abbreviations with only one relevant character in
 32.1352 +    the text always enforces an explicit popup, regardless of
 32.1353 +    @{system_option_ref jedit_completion_immediate}.
 32.1354  \<close>
 32.1355  
 32.1356  
 32.1357  subsection \<open>Completion popup \label{sec:completion-popup}\<close>
 32.1358  
 32.1359  text \<open>
 32.1360 -  A \<^emph>\<open>completion popup\<close> is a minimally invasive GUI component over the
 32.1361 -  text area that offers a selection of completion items to be inserted into
 32.1362 -  the text, e.g.\ by mouse clicks. Items are sorted dynamically, according to
 32.1363 -  the frequency of selection, with persistent history. The popup may interpret
 32.1364 -  special keys \<^verbatim>\<open>ENTER\<close>, \<^verbatim>\<open>TAB\<close>, \<^verbatim>\<open>ESCAPE\<close>,
 32.1365 -  \<^verbatim>\<open>UP\<close>, \<^verbatim>\<open>DOWN\<close>, \<^verbatim>\<open>PAGE_UP\<close>, \<^verbatim>\<open>PAGE_DOWN\<close>, but all other key events are
 32.1366 -  passed to the underlying text area.
 32.1367 -  This allows to ignore unwanted completions most of the time and continue
 32.1368 -  typing quickly. Thus the popup serves as a mechanism of confirmation of
 32.1369 -  proposed items, but the default is to continue without completion.
 32.1370 +  A \<^emph>\<open>completion popup\<close> is a minimally invasive GUI component over the text
 32.1371 +  area that offers a selection of completion items to be inserted into the
 32.1372 +  text, e.g.\ by mouse clicks. Items are sorted dynamically, according to the
 32.1373 +  frequency of selection, with persistent history. The popup may interpret
 32.1374 +  special keys \<^verbatim>\<open>ENTER\<close>, \<^verbatim>\<open>TAB\<close>, \<^verbatim>\<open>ESCAPE\<close>, \<^verbatim>\<open>UP\<close>, \<^verbatim>\<open>DOWN\<close>, \<^verbatim>\<open>PAGE_UP\<close>,
 32.1375 +  \<^verbatim>\<open>PAGE_DOWN\<close>, but all other key events are passed to the underlying text
 32.1376 +  area. This allows to ignore unwanted completions most of the time and
 32.1377 +  continue typing quickly. Thus the popup serves as a mechanism of
 32.1378 +  confirmation of proposed items, but the default is to continue without
 32.1379 +  completion.
 32.1380  
 32.1381    The meaning of special keys is as follows:
 32.1382  
 32.1383 @@ -1383,9 +1350,9 @@
 32.1384    \end{tabular}
 32.1385    \<^medskip>
 32.1386  
 32.1387 -  Movement within the popup is only active for multiple items.
 32.1388 -  Otherwise the corresponding key event retains its standard meaning
 32.1389 -  within the underlying text area.
 32.1390 +  Movement within the popup is only active for multiple items. Otherwise the
 32.1391 +  corresponding key event retains its standard meaning within the underlying
 32.1392 +  text area.
 32.1393  \<close>
 32.1394  
 32.1395  
 32.1396 @@ -1401,32 +1368,31 @@
 32.1397    all combinations make sense. At least the following important cases are
 32.1398    well-defined:
 32.1399  
 32.1400 -  \<^descr>[No selection.] The original is removed and the replacement inserted,
 32.1401 -  depending on the caret position.
 32.1402 +    \<^descr>[No selection.] The original is removed and the replacement inserted,
 32.1403 +    depending on the caret position.
 32.1404  
 32.1405 -  \<^descr>[Rectangular selection of zero width.] This special case is treated by
 32.1406 -  jEdit as ``tall caret'' and insertion of completion imitates its normal
 32.1407 -  behaviour: separate copies of the replacement are inserted for each line of
 32.1408 -  the selection.
 32.1409 +    \<^descr>[Rectangular selection of zero width.] This special case is treated by
 32.1410 +    jEdit as ``tall caret'' and insertion of completion imitates its normal
 32.1411 +    behaviour: separate copies of the replacement are inserted for each line
 32.1412 +    of the selection.
 32.1413  
 32.1414 -  \<^descr>[Other rectangular selection or multiple selections.] Here the original
 32.1415 -  is removed and the replacement is inserted for each line (or segment) of the
 32.1416 -  selection.
 32.1417 -
 32.1418 +    \<^descr>[Other rectangular selection or multiple selections.] Here the original
 32.1419 +    is removed and the replacement is inserted for each line (or segment) of
 32.1420 +    the selection.
 32.1421  
 32.1422 -  Support for multiple selections is particularly useful for
 32.1423 -  \<^emph>\<open>HyperSearch\<close>: clicking on one of the items in the \<^emph>\<open>HyperSearch
 32.1424 -  Results\<close> window makes jEdit select all its occurrences in the corresponding
 32.1425 -  line of text. Then explicit completion can be invoked via \<^verbatim>\<open>C+b\<close>,
 32.1426 -  e.g.\ to replace occurrences of \<^verbatim>\<open>-->\<close> by \<open>\<longrightarrow>\<close>.
 32.1427 +  Support for multiple selections is particularly useful for \<^emph>\<open>HyperSearch\<close>:
 32.1428 +  clicking on one of the items in the \<^emph>\<open>HyperSearch Results\<close> window makes
 32.1429 +  jEdit select all its occurrences in the corresponding line of text. Then
 32.1430 +  explicit completion can be invoked via \<^verbatim>\<open>C+b\<close>, e.g.\ to replace occurrences
 32.1431 +  of \<^verbatim>\<open>-->\<close> by \<open>\<longrightarrow>\<close>.
 32.1432  
 32.1433    \<^medskip>
 32.1434 -  Insertion works by removing and inserting pieces of text from the
 32.1435 -  buffer. This counts as one atomic operation on the jEdit history. Thus
 32.1436 -  unintended completions may be reverted by the regular @{action undo} action
 32.1437 -  of jEdit. According to normal jEdit policies, the recovered text after
 32.1438 -  @{action undo} is selected: \<^verbatim>\<open>ESCAPE\<close> is required to reset the
 32.1439 -  selection and to continue typing more text.
 32.1440 +  Insertion works by removing and inserting pieces of text from the buffer.
 32.1441 +  This counts as one atomic operation on the jEdit history. Thus unintended
 32.1442 +  completions may be reverted by the regular @{action undo} action of jEdit.
 32.1443 +  According to normal jEdit policies, the recovered text after @{action undo}
 32.1444 +  is selected: \<^verbatim>\<open>ESCAPE\<close> is required to reset the selection and to continue
 32.1445 +  typing more text.
 32.1446  \<close>
 32.1447  
 32.1448  
 32.1449 @@ -1434,8 +1400,8 @@
 32.1450  
 32.1451  text \<open>
 32.1452    This is a summary of Isabelle/Scala system options that are relevant for
 32.1453 -  completion. They may be configured in \<^emph>\<open>Plugin Options~/ Isabelle~/
 32.1454 -  General\<close> as usual.
 32.1455 +  completion. They may be configured in \<^emph>\<open>Plugin Options~/ Isabelle~/ General\<close>
 32.1456 +  as usual.
 32.1457  
 32.1458    \<^item> @{system_option_def completion_limit} specifies the maximum number of
 32.1459    items for various semantic completion operations (name-space entries etc.)
 32.1460 @@ -1444,10 +1410,10 @@
 32.1461    regular jEdit key events (\secref{sec:completion-input}): it allows to
 32.1462    disable implicit completion altogether.
 32.1463  
 32.1464 -  \<^item> @{system_option_def jedit_completion_select_enter} and
 32.1465 -  @{system_option_def jedit_completion_select_tab} enable keys to select a
 32.1466 -  completion item from the popup (\secref{sec:completion-popup}). Note that a
 32.1467 -  regular mouse click on the list of items is always possible.
 32.1468 +  \<^item> @{system_option_def jedit_completion_select_enter} and @{system_option_def
 32.1469 +  jedit_completion_select_tab} enable keys to select a completion item from
 32.1470 +  the popup (\secref{sec:completion-popup}). Note that a regular mouse click
 32.1471 +  on the list of items is always possible.
 32.1472  
 32.1473    \<^item> @{system_option_def jedit_completion_context} specifies whether the
 32.1474    language context provided by the prover should be used at all. Disabling
 32.1475 @@ -1459,17 +1425,17 @@
 32.1476    jedit_completion_immediate} determine the handling of keyboard events for
 32.1477    implicit completion (\secref{sec:completion-input}).
 32.1478  
 32.1479 -  A @{system_option jedit_completion_delay}~\<^verbatim>\<open>> 0\<close> postpones the
 32.1480 -  processing of key events, until after the user has stopped typing for the
 32.1481 -  given time span, but @{system_option jedit_completion_immediate}~\<^verbatim>\<open>"= true\<close>
 32.1482 -  means that abbreviations of Isabelle symbols are handled nonetheless.
 32.1483 +  A @{system_option jedit_completion_delay}~\<^verbatim>\<open>> 0\<close> postpones the processing of
 32.1484 +  key events, until after the user has stopped typing for the given time span,
 32.1485 +  but @{system_option jedit_completion_immediate}~\<^verbatim>\<open>"= true\<close> means that
 32.1486 +  abbreviations of Isabelle symbols are handled nonetheless.
 32.1487  
 32.1488    \<^item> @{system_option_def jedit_completion_path_ignore} specifies ``glob''
 32.1489    patterns to ignore in file-system path completion (separated by colons),
 32.1490    e.g.\ backup files ending with tilde.
 32.1491  
 32.1492 -  \<^item> @{system_option_def spell_checker} is a global guard for all
 32.1493 -  spell-checker operations: it allows to disable that mechanism altogether.
 32.1494 +  \<^item> @{system_option_def spell_checker} is a global guard for all spell-checker
 32.1495 +  operations: it allows to disable that mechanism altogether.
 32.1496  
 32.1497    \<^item> @{system_option_def spell_checker_dictionary} determines the current
 32.1498    dictionary, taken from the colon-separated list in the settings variable
 32.1499 @@ -1478,9 +1444,9 @@
 32.1500    permanent dictionary updates is stored in the directory @{file_unchecked
 32.1501    "$ISABELLE_HOME_USER/dictionaries"}, in a separate file for each dictionary.
 32.1502  
 32.1503 -  \<^item> @{system_option_def spell_checker_elements} specifies a
 32.1504 -  comma-separated list of markup elements that delimit words in the source
 32.1505 -  that is subject to spell-checking, including various forms of comments.
 32.1506 +  \<^item> @{system_option_def spell_checker_elements} specifies a comma-separated
 32.1507 +  list of markup elements that delimit words in the source that is subject to
 32.1508 +  spell-checking, including various forms of comments.
 32.1509  \<close>
 32.1510  
 32.1511  
 32.1512 @@ -1489,22 +1455,21 @@
 32.1513  text \<open>
 32.1514    Continuous document processing works asynchronously in the background.
 32.1515    Visible document source that has been evaluated may get augmented by
 32.1516 -  additional results of \<^emph>\<open>asynchronous print functions\<close>. The canonical
 32.1517 -  example is proof state output, which is always enabled. More heavy-weight
 32.1518 -  print functions may be applied, in order to prove or disprove parts of the
 32.1519 -  formal text by other means.
 32.1520 +  additional results of \<^emph>\<open>asynchronous print functions\<close>. The canonical example
 32.1521 +  is proof state output, which is always enabled. More heavy-weight print
 32.1522 +  functions may be applied, in order to prove or disprove parts of the formal
 32.1523 +  text by other means.
 32.1524  
 32.1525 -  Isabelle/HOL provides various automatically tried tools that operate
 32.1526 -  on outermost goal statements (e.g.\ @{command lemma}, @{command
 32.1527 -  theorem}), independently of the state of the current proof attempt.
 32.1528 -  They work implicitly without any arguments.  Results are output as
 32.1529 -  \<^emph>\<open>information messages\<close>, which are indicated in the text area by
 32.1530 -  blue squiggles and a blue information sign in the gutter (see
 32.1531 -  \figref{fig:auto-tools}).  The message content may be shown as for
 32.1532 -  other output (see also \secref{sec:output}).  Some tools
 32.1533 -  produce output with \<^emph>\<open>sendback\<close> markup, which means that
 32.1534 -  clicking on certain parts of the output inserts that text into the
 32.1535 -  source in the proper place.
 32.1536 +  Isabelle/HOL provides various automatically tried tools that operate on
 32.1537 +  outermost goal statements (e.g.\ @{command lemma}, @{command theorem}),
 32.1538 +  independently of the state of the current proof attempt. They work
 32.1539 +  implicitly without any arguments. Results are output as \<^emph>\<open>information
 32.1540 +  messages\<close>, which are indicated in the text area by blue squiggles and a blue
 32.1541 +  information sign in the gutter (see \figref{fig:auto-tools}). The message
 32.1542 +  content may be shown as for other output (see also \secref{sec:output}).
 32.1543 +  Some tools produce output with \<^emph>\<open>sendback\<close> markup, which means that clicking
 32.1544 +  on certain parts of the output inserts that text into the source in the
 32.1545 +  proper place.
 32.1546  
 32.1547    \begin{figure}[htb]
 32.1548    \begin{center}
 32.1549 @@ -1515,85 +1480,81 @@
 32.1550    \end{figure}
 32.1551  
 32.1552    \<^medskip>
 32.1553 -  The following Isabelle system options control the behavior
 32.1554 -  of automatically tried tools (see also the jEdit dialog window
 32.1555 -  \<^emph>\<open>Plugin Options~/ Isabelle~/ General~/ Automatically tried
 32.1556 -  tools\<close>):
 32.1557 +  The following Isabelle system options control the behavior of automatically
 32.1558 +  tried tools (see also the jEdit dialog window \<^emph>\<open>Plugin Options~/ Isabelle~/
 32.1559 +  General~/ Automatically tried tools\<close>):
 32.1560  
 32.1561 -  \<^item> @{system_option_ref auto_methods} controls automatic use of a
 32.1562 -  combination of standard proof methods (@{method auto}, @{method
 32.1563 -  simp}, @{method blast}, etc.).  This corresponds to the Isar command
 32.1564 -  @{command_ref "try0"} @{cite "isabelle-isar-ref"}.
 32.1565 +  \<^item> @{system_option_ref auto_methods} controls automatic use of a combination
 32.1566 +  of standard proof methods (@{method auto}, @{method simp}, @{method blast},
 32.1567 +  etc.). This corresponds to the Isar command @{command_ref "try0"} @{cite
 32.1568 +  "isabelle-isar-ref"}.
 32.1569  
 32.1570    The tool is disabled by default, since unparameterized invocation of
 32.1571 -  standard proof methods often consumes substantial CPU resources
 32.1572 -  without leading to success.
 32.1573 +  standard proof methods often consumes substantial CPU resources without
 32.1574 +  leading to success.
 32.1575  
 32.1576 -  \<^item> @{system_option_ref auto_nitpick} controls a slightly reduced
 32.1577 -  version of @{command_ref nitpick}, which tests for counterexamples using
 32.1578 -  first-order relational logic. See also the Nitpick manual
 32.1579 -  @{cite "isabelle-nitpick"}.
 32.1580 +  \<^item> @{system_option_ref auto_nitpick} controls a slightly reduced version of
 32.1581 +  @{command_ref nitpick}, which tests for counterexamples using first-order
 32.1582 +  relational logic. See also the Nitpick manual @{cite "isabelle-nitpick"}.
 32.1583  
 32.1584 -  This tool is disabled by default, due to the extra overhead of
 32.1585 -  invoking an external Java process for each attempt to disprove a
 32.1586 -  subgoal.
 32.1587 +  This tool is disabled by default, due to the extra overhead of invoking an
 32.1588 +  external Java process for each attempt to disprove a subgoal.
 32.1589  
 32.1590    \<^item> @{system_option_ref auto_quickcheck} controls automatic use of
 32.1591 -  @{command_ref quickcheck}, which tests for counterexamples using a
 32.1592 -  series of assignments for free variables of a subgoal.
 32.1593 +  @{command_ref quickcheck}, which tests for counterexamples using a series of
 32.1594 +  assignments for free variables of a subgoal.
 32.1595  
 32.1596 -  This tool is \<^emph>\<open>enabled\<close> by default.  It requires little
 32.1597 -  overhead, but is a bit weaker than @{command nitpick}.
 32.1598 +  This tool is \<^emph>\<open>enabled\<close> by default. It requires little overhead, but is a
 32.1599 +  bit weaker than @{command nitpick}.
 32.1600  
 32.1601 -  \<^item> @{system_option_ref auto_sledgehammer} controls a significantly
 32.1602 -  reduced version of @{command_ref sledgehammer}, which attempts to prove
 32.1603 -  a subgoal using external automatic provers. See also the
 32.1604 -  Sledgehammer manual @{cite "isabelle-sledgehammer"}.
 32.1605 +  \<^item> @{system_option_ref auto_sledgehammer} controls a significantly reduced
 32.1606 +  version of @{command_ref sledgehammer}, which attempts to prove a subgoal
 32.1607 +  using external automatic provers. See also the Sledgehammer manual @{cite
 32.1608 +  "isabelle-sledgehammer"}.
 32.1609  
 32.1610 -  This tool is disabled by default, due to the relatively heavy nature
 32.1611 -  of Sledgehammer.
 32.1612 +  This tool is disabled by default, due to the relatively heavy nature of
 32.1613 +  Sledgehammer.
 32.1614  
 32.1615    \<^item> @{system_option_ref auto_solve_direct} controls automatic use of
 32.1616 -  @{command_ref solve_direct}, which checks whether the current subgoals
 32.1617 -  can be solved directly by an existing theorem.  This also helps to
 32.1618 -  detect duplicate lemmas.
 32.1619 +  @{command_ref solve_direct}, which checks whether the current subgoals can
 32.1620 +  be solved directly by an existing theorem. This also helps to detect
 32.1621 +  duplicate lemmas.
 32.1622  
 32.1623    This tool is \<^emph>\<open>enabled\<close> by default.
 32.1624  
 32.1625  
 32.1626 -  Invocation of automatically tried tools is subject to some global
 32.1627 -  policies of parallel execution, which may be configured as follows:
 32.1628 +  Invocation of automatically tried tools is subject to some global policies
 32.1629 +  of parallel execution, which may be configured as follows:
 32.1630  
 32.1631 -  \<^item> @{system_option_ref auto_time_limit} (default 2.0) determines the
 32.1632 -  timeout (in seconds) for each tool execution.
 32.1633 +  \<^item> @{system_option_ref auto_time_limit} (default 2.0) determines the timeout
 32.1634 +  (in seconds) for each tool execution.
 32.1635  
 32.1636 -  \<^item> @{system_option_ref auto_time_start} (default 1.0) determines the
 32.1637 -  start delay (in seconds) for automatically tried tools, after the
 32.1638 -  main command evaluation is finished.
 32.1639 +  \<^item> @{system_option_ref auto_time_start} (default 1.0) determines the start
 32.1640 +  delay (in seconds) for automatically tried tools, after the main command
 32.1641 +  evaluation is finished.
 32.1642  
 32.1643  
 32.1644 -  Each tool is submitted independently to the pool of parallel
 32.1645 -  execution tasks in Isabelle/ML, using hardwired priorities according
 32.1646 -  to its relative ``heaviness''.  The main stages of evaluation and
 32.1647 -  printing of proof states take precedence, but an already running
 32.1648 -  tool is not canceled and may thus reduce reactivity of proof
 32.1649 -  document processing.
 32.1650 +  Each tool is submitted independently to the pool of parallel execution tasks
 32.1651 +  in Isabelle/ML, using hardwired priorities according to its relative
 32.1652 +  ``heaviness''. The main stages of evaluation and printing of proof states
 32.1653 +  take precedence, but an already running tool is not canceled and may thus
 32.1654 +  reduce reactivity of proof document processing.
 32.1655  
 32.1656 -  Users should experiment how the available CPU resources (number of
 32.1657 -  cores) are best invested to get additional feedback from prover in
 32.1658 -  the background, by using a selection of weaker or stronger tools.
 32.1659 +  Users should experiment how the available CPU resources (number of cores)
 32.1660 +  are best invested to get additional feedback from prover in the background,
 32.1661 +  by using a selection of weaker or stronger tools.
 32.1662  \<close>
 32.1663  
 32.1664  
 32.1665  section \<open>Sledgehammer \label{sec:sledgehammer}\<close>
 32.1666  
 32.1667 -text \<open>The \<^emph>\<open>Sledgehammer\<close> panel (\figref{fig:sledgehammer})
 32.1668 -  provides a view on some independent execution of the Isar command
 32.1669 -  @{command_ref sledgehammer}, with process indicator (spinning wheel) and
 32.1670 -  GUI elements for important Sledgehammer arguments and options.  Any
 32.1671 -  number of Sledgehammer panels may be active, according to the
 32.1672 -  standard policies of Dockable Window Management in jEdit.  Closing
 32.1673 -  such windows also cancels the corresponding prover tasks.
 32.1674 +text \<open>
 32.1675 +  The \<^emph>\<open>Sledgehammer\<close> panel (\figref{fig:sledgehammer}) provides a view on
 32.1676 +  some independent execution of the Isar command @{command_ref sledgehammer},
 32.1677 +  with process indicator (spinning wheel) and GUI elements for important
 32.1678 +  Sledgehammer arguments and options. Any number of Sledgehammer panels may be
 32.1679 +  active, according to the standard policies of Dockable Window Management in
 32.1680 +  jEdit. Closing such windows also cancels the corresponding prover tasks.
 32.1681  
 32.1682    \begin{figure}[htb]
 32.1683    \begin{center}
 32.1684 @@ -1603,34 +1564,37 @@
 32.1685    \label{fig:sledgehammer}
 32.1686    \end{figure}
 32.1687  
 32.1688 -  The \<^emph>\<open>Apply\<close> button attaches a fresh invocation of @{command
 32.1689 -  sledgehammer} to the command where the cursor is pointing in the
 32.1690 -  text --- this should be some pending proof problem.  Further buttons
 32.1691 -  like \<^emph>\<open>Cancel\<close> and \<^emph>\<open>Locate\<close> help to manage the running
 32.1692 -  process.
 32.1693 +  The \<^emph>\<open>Apply\<close> button attaches a fresh invocation of @{command sledgehammer}
 32.1694 +  to the command where the cursor is pointing in the text --- this should be
 32.1695 +  some pending proof problem. Further buttons like \<^emph>\<open>Cancel\<close> and \<^emph>\<open>Locate\<close>
 32.1696 +  help to manage the running process.
 32.1697  
 32.1698 -  Results appear incrementally in the output window of the panel.
 32.1699 -  Proposed proof snippets are marked-up as \<^emph>\<open>sendback\<close>, which
 32.1700 -  means a single mouse click inserts the text into a suitable place of
 32.1701 -  the original source.  Some manual editing may be required
 32.1702 -  nonetheless, say to remove earlier proof attempts.\<close>
 32.1703 +  Results appear incrementally in the output window of the panel. Proposed
 32.1704 +  proof snippets are marked-up as \<^emph>\<open>sendback\<close>, which means a single mouse
 32.1705 +  click inserts the text into a suitable place of the original source. Some
 32.1706 +  manual editing may be required nonetheless, say to remove earlier proof
 32.1707 +  attempts.
 32.1708 +\<close>
 32.1709  
 32.1710  
 32.1711  chapter \<open>Isabelle document preparation\<close>
 32.1712  
 32.1713 -text \<open>The ultimate purpose of Isabelle is to produce nicely rendered documents
 32.1714 +text \<open>
 32.1715 +  The ultimate purpose of Isabelle is to produce nicely rendered documents
 32.1716    with the Isabelle document preparation system, which is based on {\LaTeX};
 32.1717    see also @{cite "isabelle-system" and "isabelle-isar-ref"}. Isabelle/jEdit
 32.1718 -  provides some additional support for document editing.\<close>
 32.1719 +  provides some additional support for document editing.
 32.1720 +\<close>
 32.1721  
 32.1722  
 32.1723  section \<open>Document outline\<close>
 32.1724  
 32.1725 -text \<open>Theory sources may contain document markup commands, such as
 32.1726 -  @{command_ref chapter}, @{command_ref section}, @{command subsection}. The
 32.1727 -  Isabelle SideKick parser (\secref{sec:sidekick}) represents this document
 32.1728 -  outline as structured tree view, with formal statements and proofs nested
 32.1729 -  inside; see \figref{fig:sidekick-document}.
 32.1730 +text \<open>
 32.1731 +  Theory sources may contain document markup commands, such as @{command_ref
 32.1732 +  chapter}, @{command_ref section}, @{command subsection}. The Isabelle
 32.1733 +  SideKick parser (\secref{sec:sidekick}) represents this document outline as
 32.1734 +  structured tree view, with formal statements and proofs nested inside; see
 32.1735 +  \figref{fig:sidekick-document}.
 32.1736  
 32.1737    \begin{figure}[htb]
 32.1738    \begin{center}
 32.1739 @@ -1641,25 +1605,27 @@
 32.1740    \end{figure}
 32.1741  
 32.1742    It is also possible to use text folding according to this structure, by
 32.1743 -  adjusting \<^emph>\<open>Utilities / Buffer Options / Folding mode\<close> of jEdit. The
 32.1744 -  default mode \<^verbatim>\<open>isabelle\<close> uses the structure of formal definitions,
 32.1745 -  statements, and proofs. The alternative mode \<^verbatim>\<open>sidekick\<close> uses the
 32.1746 -  document structure of the SideKick parser, as explained above.\<close>
 32.1747 +  adjusting \<^emph>\<open>Utilities / Buffer Options / Folding mode\<close> of jEdit. The default
 32.1748 +  mode \<^verbatim>\<open>isabelle\<close> uses the structure of formal definitions, statements, and
 32.1749 +  proofs. The alternative mode \<^verbatim>\<open>sidekick\<close> uses the document structure of the
 32.1750 +  SideKick parser, as explained above.
 32.1751 +\<close>
 32.1752  
 32.1753  
 32.1754  section \<open>Citations and Bib{\TeX} entries\<close>
 32.1755  
 32.1756 -text \<open>Citations are managed by {\LaTeX} and Bib{\TeX} in \<^verbatim>\<open>.bib\<close>
 32.1757 -  files. The Isabelle session build process and the @{tool latex} tool @{cite
 32.1758 +text \<open>
 32.1759 +  Citations are managed by {\LaTeX} and Bib{\TeX} in \<^verbatim>\<open>.bib\<close> files. The
 32.1760 +  Isabelle session build process and the @{tool latex} tool @{cite
 32.1761    "isabelle-system"} are smart enough to assemble the result, based on the
 32.1762    session directory layout.
 32.1763  
 32.1764    The document antiquotation \<open>@{cite}\<close> is described in @{cite
 32.1765    "isabelle-isar-ref"}. Within the Prover IDE it provides semantic markup for
 32.1766    tooltips, hyperlinks, and completion for Bib{\TeX} database entries.
 32.1767 -  Isabelle/jEdit does \<^emph>\<open>not\<close> know about the actual Bib{\TeX} environment
 32.1768 -  used in {\LaTeX} batch-mode, but it can take citations from those \<^verbatim>\<open>.bib\<close>
 32.1769 -  files that happen to be open in the editor; see \figref{fig:cite-completion}.
 32.1770 +  Isabelle/jEdit does \<^emph>\<open>not\<close> know about the actual Bib{\TeX} environment used
 32.1771 +  in {\LaTeX} batch-mode, but it can take citations from those \<^verbatim>\<open>.bib\<close> files
 32.1772 +  that happen to be open in the editor; see \figref{fig:cite-completion}.
 32.1773  
 32.1774    \begin{figure}[htb]
 32.1775    \begin{center}
 32.1776 @@ -1669,9 +1635,9 @@
 32.1777    \label{fig:cite-completion}
 32.1778    \end{figure}
 32.1779  
 32.1780 -  Isabelle/jEdit also provides some support for editing \<^verbatim>\<open>.bib\<close>
 32.1781 -  files themselves. There is syntax highlighting based on entry types
 32.1782 -  (according to standard Bib{\TeX} styles), a context-menu to compose entries
 32.1783 +  Isabelle/jEdit also provides some support for editing \<^verbatim>\<open>.bib\<close> files
 32.1784 +  themselves. There is syntax highlighting based on entry types (according to
 32.1785 +  standard Bib{\TeX} styles), a context-menu to compose entries
 32.1786    systematically, and a SideKick tree view of the overall content; see
 32.1787    \figref{fig:bibtex-mode}.
 32.1788  
 32.1789 @@ -1689,35 +1655,33 @@
 32.1790  
 32.1791  section \<open>Timing\<close>
 32.1792  
 32.1793 -text \<open>Managed evaluation of commands within PIDE documents includes
 32.1794 -  timing information, which consists of elapsed (wall-clock) time, CPU
 32.1795 -  time, and GC (garbage collection) time.  Note that in a
 32.1796 -  multithreaded system it is difficult to measure execution time
 32.1797 -  precisely: elapsed time is closer to the real requirements of
 32.1798 -  runtime resources than CPU or GC time, which are both subject to
 32.1799 -  influences from the parallel environment that are outside the scope
 32.1800 -  of the current command transaction.
 32.1801 +text \<open>
 32.1802 +  Managed evaluation of commands within PIDE documents includes timing
 32.1803 +  information, which consists of elapsed (wall-clock) time, CPU time, and GC
 32.1804 +  (garbage collection) time. Note that in a multithreaded system it is
 32.1805 +  difficult to measure execution time precisely: elapsed time is closer to the
 32.1806 +  real requirements of runtime resources than CPU or GC time, which are both
 32.1807 +  subject to influences from the parallel environment that are outside the
 32.1808 +  scope of the current command transaction.
 32.1809  
 32.1810 -  The \<^emph>\<open>Timing\<close> panel provides an overview of cumulative command
 32.1811 -  timings for each document node.  Commands with elapsed time below
 32.1812 -  the given threshold are ignored in the grand total.  Nodes are
 32.1813 -  sorted according to their overall timing.  For the document node
 32.1814 -  that corresponds to the current buffer, individual command timings
 32.1815 -  are shown as well.  A double-click on a theory node or command moves
 32.1816 -  the editor focus to that particular source position.
 32.1817 +  The \<^emph>\<open>Timing\<close> panel provides an overview of cumulative command timings for
 32.1818 +  each document node. Commands with elapsed time below the given threshold are
 32.1819 +  ignored in the grand total. Nodes are sorted according to their overall
 32.1820 +  timing. For the document node that corresponds to the current buffer,
 32.1821 +  individual command timings are shown as well. A double-click on a theory
 32.1822 +  node or command moves the editor focus to that particular source position.
 32.1823  
 32.1824 -  It is also possible to reveal individual timing information via some
 32.1825 -  tooltip for the corresponding command keyword, using the technique
 32.1826 -  of mouse hovering with \<^verbatim>\<open>CONTROL\<close>/\<^verbatim>\<open>COMMAND\<close>
 32.1827 -  modifier key as explained in \secref{sec:tooltips-hyperlinks}.
 32.1828 -  Actual display of timing depends on the global option
 32.1829 -  @{system_option_ref jedit_timing_threshold}, which can be configured in
 32.1830 -  \<^emph>\<open>Plugin Options~/ Isabelle~/ General\<close>.
 32.1831 +  It is also possible to reveal individual timing information via some tooltip
 32.1832 +  for the corresponding command keyword, using the technique of mouse hovering
 32.1833 +  with \<^verbatim>\<open>CONTROL\<close>~/ \<^verbatim>\<open>COMMAND\<close> modifier key as explained in
 32.1834 +  \secref{sec:tooltips-hyperlinks}. Actual display of timing depends on the
 32.1835 +  global option @{system_option_ref jedit_timing_threshold}, which can be
 32.1836 +  configured in \<^emph>\<open>Plugin Options~/ Isabelle~/ General\<close>.
 32.1837  
 32.1838    \<^medskip>
 32.1839 -  The \<^emph>\<open>Monitor\<close> panel visualizes various data collections about
 32.1840 -  recent activity of the Isabelle/ML task farm and the underlying ML runtime
 32.1841 -  system. The display is continuously updated according to @{system_option_ref
 32.1842 +  The \<^emph>\<open>Monitor\<close> panel visualizes various data collections about recent
 32.1843 +  activity of the Isabelle/ML task farm and the underlying ML runtime system.
 32.1844 +  The display is continuously updated according to @{system_option_ref
 32.1845    editor_chart_delay}. Note that the painting of the chart takes considerable
 32.1846    runtime itself --- on the Java Virtual Machine that runs Isabelle/Scala, not
 32.1847    Isabelle/ML. Internally, the Isabelle/Scala module \<^verbatim>\<open>isabelle.ML_Statistics\<close>
 32.1848 @@ -1727,32 +1691,30 @@
 32.1849  
 32.1850  section \<open>Low-level output\<close>
 32.1851  
 32.1852 -text \<open>Prover output is normally shown directly in the main text area
 32.1853 -  or secondary \<^emph>\<open>Output\<close> panels, as explained in
 32.1854 -  \secref{sec:output}.
 32.1855 +text \<open>
 32.1856 +  Prover output is normally shown directly in the main text area or secondary
 32.1857 +  \<^emph>\<open>Output\<close> panels, as explained in \secref{sec:output}.
 32.1858  
 32.1859 -  Beyond this, it is occasionally useful to inspect low-level output
 32.1860 -  channels via some of the following additional panels:
 32.1861 +  Beyond this, it is occasionally useful to inspect low-level output channels
 32.1862 +  via some of the following additional panels:
 32.1863  
 32.1864 -  \<^item> \<^emph>\<open>Protocol\<close> shows internal messages between the
 32.1865 -  Isabelle/Scala and Isabelle/ML side of the PIDE document editing protocol.
 32.1866 -  Recording of messages starts with the first activation of the
 32.1867 -  corresponding dockable window; earlier messages are lost.
 32.1868 +  \<^item> \<^emph>\<open>Protocol\<close> shows internal messages between the Isabelle/Scala and
 32.1869 +  Isabelle/ML side of the PIDE document editing protocol. Recording of
 32.1870 +  messages starts with the first activation of the corresponding dockable
 32.1871 +  window; earlier messages are lost.
 32.1872  
 32.1873 -  Actual display of protocol messages causes considerable slowdown, so
 32.1874 -  it is important to undock all \<^emph>\<open>Protocol\<close> panels for production
 32.1875 -  work.
 32.1876 +  Actual display of protocol messages causes considerable slowdown, so it is
 32.1877 +  important to undock all \<^emph>\<open>Protocol\<close> panels for production work.
 32.1878  
 32.1879    \<^item> \<^emph>\<open>Raw Output\<close> shows chunks of text from the \<^verbatim>\<open>stdout\<close> and \<^verbatim>\<open>stderr\<close>
 32.1880 -  channels of the prover process.
 32.1881 -  Recording of output starts with the first activation of the
 32.1882 -  corresponding dockable window; earlier output is lost.
 32.1883 +  channels of the prover process. Recording of output starts with the first
 32.1884 +  activation of the corresponding dockable window; earlier output is lost.
 32.1885  
 32.1886 -  The implicit stateful nature of physical I/O channels makes it
 32.1887 -  difficult to relate raw output to the actual command from where it
 32.1888 -  was originating.  Parallel execution may add to the confusion.
 32.1889 -  Peeking at physical process I/O is only the last resort to diagnose
 32.1890 -  problems with tools that are not PIDE compliant.
 32.1891 +  The implicit stateful nature of physical I/O channels makes it difficult to
 32.1892 +  relate raw output to the actual command from where it was originating.
 32.1893 +  Parallel execution may add to the confusion. Peeking at physical process I/O
 32.1894 +  is only the last resort to diagnose problems with tools that are not PIDE
 32.1895 +  compliant.
 32.1896  
 32.1897    Under normal circumstances, prover output always works via managed message
 32.1898    channels (corresponding to @{ML writeln}, @{ML warning}, @{ML
 32.1899 @@ -1762,50 +1724,45 @@
 32.1900  
 32.1901    \<^item> \<^emph>\<open>Syslog\<close> shows system messages that might be relevant to diagnose
 32.1902    problems with the startup or shutdown phase of the prover process; this also
 32.1903 -  includes raw output on \<^verbatim>\<open>stderr\<close>. Isabelle/ML also provides an
 32.1904 -  explicit @{ML Output.system_message} operation, which is occasionally useful
 32.1905 -  for diagnostic purposes within the system infrastructure itself.
 32.1906 +  includes raw output on \<^verbatim>\<open>stderr\<close>. Isabelle/ML also provides an explicit @{ML
 32.1907 +  Output.system_message} operation, which is occasionally useful for
 32.1908 +  diagnostic purposes within the system infrastructure itself.
 32.1909  
 32.1910 -  A limited amount of syslog messages are buffered, independently of
 32.1911 -  the docking state of the \<^emph>\<open>Syslog\<close> panel.  This allows to
 32.1912 -  diagnose serious problems with Isabelle/PIDE process management,
 32.1913 -  outside of the actual protocol layer.
 32.1914 +  A limited amount of syslog messages are buffered, independently of the
 32.1915 +  docking state of the \<^emph>\<open>Syslog\<close> panel. This allows to diagnose serious
 32.1916 +  problems with Isabelle/PIDE process management, outside of the actual
 32.1917 +  protocol layer.
 32.1918  
 32.1919 -  Under normal situations, such low-level system output can be
 32.1920 -  ignored.
 32.1921 +  Under normal situations, such low-level system output can be ignored.
 32.1922  \<close>
 32.1923  
 32.1924  
 32.1925  chapter \<open>Known problems and workarounds \label{sec:problems}\<close>
 32.1926  
 32.1927  text \<open>
 32.1928 -  \<^item> \<^bold>\<open>Problem:\<close> Odd behavior of some diagnostic commands with
 32.1929 -  global side-effects, like writing a physical file.
 32.1930 +  \<^item> \<^bold>\<open>Problem:\<close> Odd behavior of some diagnostic commands with global
 32.1931 +  side-effects, like writing a physical file.
 32.1932  
 32.1933 -  \<^bold>\<open>Workaround:\<close> Copy/paste complete command text from
 32.1934 -  elsewhere, or disable continuous checking temporarily.
 32.1935 -
 32.1936 -  \<^item> \<^bold>\<open>Problem:\<close> No direct support to remove document nodes from the
 32.1937 -  collection of theories.
 32.1938 +  \<^bold>\<open>Workaround:\<close> Copy/paste complete command text from elsewhere, or disable
 32.1939 +  continuous checking temporarily.
 32.1940  
 32.1941 -  \<^bold>\<open>Workaround:\<close> Clear the buffer content of unused files and close
 32.1942 -  \<^emph>\<open>without\<close> saving changes.
 32.1943 +  \<^item> \<^bold>\<open>Problem:\<close> No direct support to remove document nodes from the collection
 32.1944 +  of theories.
 32.1945  
 32.1946 -  \<^item> \<^bold>\<open>Problem:\<close> Keyboard shortcuts \<^verbatim>\<open>C+PLUS\<close> and
 32.1947 -  \<^verbatim>\<open>C+MINUS\<close> for adjusting the editor font size depend on
 32.1948 -  platform details and national keyboards.
 32.1949 +  \<^bold>\<open>Workaround:\<close> Clear the buffer content of unused files and close \<^emph>\<open>without\<close>
 32.1950 +  saving changes.
 32.1951  
 32.1952 -  \<^bold>\<open>Workaround:\<close> Rebind keys via \<^emph>\<open>Global Options~/
 32.1953 -  Shortcuts\<close>.
 32.1954 +  \<^item> \<^bold>\<open>Problem:\<close> Keyboard shortcuts \<^verbatim>\<open>C+PLUS\<close> and \<^verbatim>\<open>C+MINUS\<close> for adjusting the
 32.1955 +  editor font size depend on platform details and national keyboards.
 32.1956 +
 32.1957 +  \<^bold>\<open>Workaround:\<close> Rebind keys via \<^emph>\<open>Global Options~/ Shortcuts\<close>.
 32.1958  
 32.1959    \<^item> \<^bold>\<open>Problem:\<close> The Mac OS X key sequence \<^verbatim>\<open>COMMAND+COMMA\<close> for application
 32.1960 -  \<^emph>\<open>Preferences\<close> is in conflict with the
 32.1961 -  jEdit default keyboard shortcut for \<^emph>\<open>Incremental Search Bar\<close> (action
 32.1962 -  @{action_ref "quick-search"}).
 32.1963 +  \<^emph>\<open>Preferences\<close> is in conflict with the jEdit default keyboard shortcut for
 32.1964 +  \<^emph>\<open>Incremental Search Bar\<close> (action @{action_ref "quick-search"}).
 32.1965  
 32.1966 -  \<^bold>\<open>Workaround:\<close> Rebind key via \<^emph>\<open>Global Options~/
 32.1967 -  Shortcuts\<close> according to national keyboard, e.g.\ \<^verbatim>\<open>COMMAND+SLASH\<close>
 32.1968 -  on English ones.
 32.1969 +  \<^bold>\<open>Workaround:\<close> Rebind key via \<^emph>\<open>Global Options~/ Shortcuts\<close> according to
 32.1970 +  national keyboard, e.g.\ \<^verbatim>\<open>COMMAND+SLASH\<close> on English ones.
 32.1971  
 32.1972    \<^item> \<^bold>\<open>Problem:\<close> On Mac OS X with native Apple look-and-feel, some exotic
 32.1973    national keyboards may cause a conflict of menu accelerator keys with
 32.1974 @@ -1815,44 +1772,42 @@
 32.1975    \<^bold>\<open>Workaround:\<close> Disable the native Apple menu bar via Java runtime option
 32.1976    \<^verbatim>\<open>-Dapple.laf.useScreenMenuBar=false\<close>.
 32.1977  
 32.1978 -  \<^item> \<^bold>\<open>Problem:\<close> Mac OS X system fonts sometimes lead to
 32.1979 -  character drop-outs in the main text area.
 32.1980 +  \<^item> \<^bold>\<open>Problem:\<close> Mac OS X system fonts sometimes lead to character drop-outs in
 32.1981 +  the main text area.
 32.1982  
 32.1983 -  \<^bold>\<open>Workaround:\<close> Use the default \<^verbatim>\<open>IsabelleText\<close> font.
 32.1984 -  (Do not install that font on the system.)
 32.1985 -
 32.1986 -  \<^item> \<^bold>\<open>Problem:\<close> Some Linux/X11 input methods such as IBus
 32.1987 -  tend to disrupt key event handling of Java/AWT/Swing.
 32.1988 +  \<^bold>\<open>Workaround:\<close> Use the default \<^verbatim>\<open>IsabelleText\<close> font. (Do not install that
 32.1989 +  font on the system.)
 32.1990  
 32.1991 -  \<^bold>\<open>Workaround:\<close> Do not use X11 input methods. Note that environment
 32.1992 -  variable \<^verbatim>\<open>XMODIFIERS\<close> is reset by default within Isabelle
 32.1993 -  settings.
 32.1994 +  \<^item> \<^bold>\<open>Problem:\<close> Some Linux/X11 input methods such as IBus tend to disrupt key
 32.1995 +  event handling of Java/AWT/Swing.
 32.1996  
 32.1997 -  \<^item> \<^bold>\<open>Problem:\<close> Some Linux/X11 window managers that are
 32.1998 -  not ``re-parenting'' cause problems with additional windows opened
 32.1999 -  by Java. This affects either historic or neo-minimalistic window
 32.2000 -  managers like \<^verbatim>\<open>awesome\<close> or \<^verbatim>\<open>xmonad\<close>.
 32.2001 +  \<^bold>\<open>Workaround:\<close> Do not use X11 input methods. Note that environment variable
 32.2002 +  \<^verbatim>\<open>XMODIFIERS\<close> is reset by default within Isabelle settings.
 32.2003 +
 32.2004 +  \<^item> \<^bold>\<open>Problem:\<close> Some Linux/X11 window managers that are not ``re-parenting''
 32.2005 +  cause problems with additional windows opened by Java. This affects either
 32.2006 +  historic or neo-minimalistic window managers like \<^verbatim>\<open>awesome\<close> or \<^verbatim>\<open>xmonad\<close>.
 32.2007  
 32.2008    \<^bold>\<open>Workaround:\<close> Use a regular re-parenting X11 window manager.
 32.2009  
 32.2010 -  \<^item> \<^bold>\<open>Problem:\<close> Various forks of Linux/X11 window managers and
 32.2011 -  desktop environments (like Gnome) disrupt the handling of menu popups and
 32.2012 -  mouse positions of Java/AWT/Swing.
 32.2013 +  \<^item> \<^bold>\<open>Problem:\<close> Various forks of Linux/X11 window managers and desktop
 32.2014 +  environments (like Gnome) disrupt the handling of menu popups and mouse
 32.2015 +  positions of Java/AWT/Swing.
 32.2016  
 32.2017    \<^bold>\<open>Workaround:\<close> Use mainstream versions of Linux desktops.
 32.2018  
 32.2019 -  \<^item> \<^bold>\<open>Problem:\<close> Native Windows look-and-feel with global font
 32.2020 -  scaling leads to bad GUI rendering of various tree views.
 32.2021 +  \<^item> \<^bold>\<open>Problem:\<close> Native Windows look-and-feel with global font scaling leads to
 32.2022 +  bad GUI rendering of various tree views.
 32.2023  
 32.2024 -  \<^bold>\<open>Workaround:\<close> Use \<^emph>\<open>Metal\<close> look-and-feel and re-adjust its
 32.2025 -  primary and secondary font as explained in \secref{sec:hdpi}.
 32.2026 +  \<^bold>\<open>Workaround:\<close> Use \<^emph>\<open>Metal\<close> look-and-feel and re-adjust its primary and
 32.2027 +  secondary font as explained in \secref{sec:hdpi}.
 32.2028  
 32.2029    \<^item> \<^bold>\<open>Problem:\<close> Full-screen mode via jEdit action @{action_ref
 32.2030 -  "toggle-full-screen"} (default keyboard shortcut \<^verbatim>\<open>F11\<close>) works on
 32.2031 -  Windows, but not on Mac OS X or various Linux/X11 window managers.
 32.2032 +  "toggle-full-screen"} (default keyboard shortcut \<^verbatim>\<open>F11\<close>) works on Windows,
 32.2033 +  but not on Mac OS X or various Linux/X11 window managers.
 32.2034  
 32.2035 -  \<^bold>\<open>Workaround:\<close> Use native full-screen control of the window
 32.2036 -  manager (notably on Mac OS X).
 32.2037 +  \<^bold>\<open>Workaround:\<close> Use native full-screen control of the window manager (notably
 32.2038 +  on Mac OS X).
 32.2039  \<close>
 32.2040  
 32.2041  end
 32.2042 \ No newline at end of file
    33.1 --- a/src/Doc/Locales/Examples1.thy	Tue Nov 10 14:18:41 2015 +0000
    33.2 +++ b/src/Doc/Locales/Examples1.thy	Tue Nov 10 14:43:29 2015 +0000
    33.3 @@ -84,6 +84,6 @@
    33.4    In order to allow for the desired replacement, interpretation
    33.5    accepts \emph{equations} in addition to the parameter instantiation.
    33.6    These follow the locale expression and are indicated with the
    33.7 -  keyword \isakeyword{where}.  This is the revised interpretation:
    33.8 +  keyword \isakeyword{rewrites}.  This is the revised interpretation:
    33.9  \<close>
   33.10  end
    34.1 --- a/src/Doc/Locales/Examples2.thy	Tue Nov 10 14:18:41 2015 +0000
    34.2 +++ b/src/Doc/Locales/Examples2.thy	Tue Nov 10 14:43:29 2015 +0000
    34.3 @@ -2,7 +2,7 @@
    34.4  imports Examples
    34.5  begin
    34.6    interpretation %visible int: partial_order "op \<le> :: [int, int] \<Rightarrow> bool"
    34.7 -    where "int.less x y = (x < y)"
    34.8 +    rewrites "int.less x y = (x < y)"
    34.9    proof -
   34.10      txt \<open>\normalsize The goals are now:
   34.11        @{subgoals [display]}
    35.1 --- a/src/Doc/Locales/Examples3.thy	Tue Nov 10 14:18:41 2015 +0000
    35.2 +++ b/src/Doc/Locales/Examples3.thy	Tue Nov 10 14:43:29 2015 +0000
    35.3 @@ -17,7 +17,7 @@
    35.4    repeat the example from the previous section to illustrate this.\<close>
    35.5  
    35.6    interpretation %visible int: partial_order "op \<le> :: int \<Rightarrow> int \<Rightarrow> bool"
    35.7 -    where "int.less x y = (x < y)"
    35.8 +    rewrites "int.less x y = (x < y)"
    35.9    proof -
   35.10      show "partial_order (op \<le> :: int \<Rightarrow> int \<Rightarrow> bool)"
   35.11        by unfold_locales auto
   35.12 @@ -47,7 +47,7 @@
   35.13    so they can be used in a later example.\<close>
   35.14  
   35.15    interpretation %visible int: lattice "op \<le> :: int \<Rightarrow> int \<Rightarrow> bool"
   35.16 -    where int_min_eq: "int.meet x y = min x y"
   35.17 +    rewrites int_min_eq: "int.meet x y = min x y"
   35.18        and int_max_eq: "int.join x y = max x y"
   35.19    proof -
   35.20      show "lattice (op \<le> :: int \<Rightarrow> int \<Rightarrow> bool)"
   35.21 @@ -486,13 +486,13 @@
   35.22    proof unfold_locales
   35.23      fix f g
   35.24      have "partial_order.is_inf (\<lambda>f g. \<forall>x. f x \<sqsubseteq> g x) f g (\<lambda>x. f x \<sqinter> g x)"
   35.25 -      apply (rule is_infI) apply rule+ apply (drule spec, assumption)+ done
   35.26 +      apply (rule f.is_infI) apply rule+ apply (drule spec, assumption)+ done
   35.27      then show "\<exists>inf. partial_order.is_inf (\<lambda>f g. \<forall>x. f x \<sqsubseteq> g x) f g inf"
   35.28        by fast
   35.29    next
   35.30      fix f g
   35.31      have "partial_order.is_sup (\<lambda>f g. \<forall>x. f x \<sqsubseteq> g x) f g (\<lambda>x. f x \<squnion> g x)"
   35.32 -      apply (rule is_supI) apply rule+ apply (drule spec, assumption)+ done
   35.33 +      apply (rule f.is_supI) apply rule+ apply (drule spec, assumption)+ done
   35.34      then show "\<exists>sup. partial_order.is_sup (\<lambda>f g. \<forall>x. f x \<sqsubseteq> g x) f g sup"
   35.35        by fast
   35.36    qed
   35.37 @@ -611,7 +611,7 @@
   35.38  
   35.39    \textit{equation} & ::= & [ \textit{attr-name} ``\textbf{:}'' ]
   35.40      \textit{prop} \\
   35.41 -  \textit{equations} & ::= &  \textbf{where} \textit{equation} ( \textbf{and}
   35.42 +  \textit{equations} & ::= &  \textbf{rewrites} \textit{equation} ( \textbf{and}
   35.43      \textit{equation} )$^*$  \\
   35.44    \textit{toplevel} & ::=
   35.45    & \textbf{sublocale} \textit{name} ( ``$<$'' $|$
    36.1 --- a/src/Doc/Nitpick/document/root.tex	Tue Nov 10 14:18:41 2015 +0000
    36.2 +++ b/src/Doc/Nitpick/document/root.tex	Tue Nov 10 14:43:29 2015 +0000
    36.3 @@ -342,8 +342,7 @@
    36.4  
    36.5  \prew
    36.6  \textbf{nitpick} [\textit{card} $'a$~= 1--50]\footnote{The symbol `--'
    36.7 -can be entered as \texttt{-} (hyphen) or
    36.8 -\texttt{\char`\\\char`\<emdash\char`\>}.} \\[2\smallskipamount]
    36.9 +is entered as \texttt{-} (hyphen).} \\[2\smallskipamount]
   36.10  \slshape Nitpick found no counterexample.
   36.11  \postw
   36.12  
   36.13 @@ -1769,7 +1768,7 @@
   36.14  \item[\labelitemi] \qtybf{int\/}: An integer. Negative integers are prefixed with a hyphen.
   36.15  \item[\labelitemi] \qtybf{smart\_int\/}: An integer or \textit{smart}.
   36.16  \item[\labelitemi] \qtybf{int\_range}: An integer (e.g., 3) or a range
   36.17 -of nonnegative integers (e.g., $1$--$4$). The range symbol `--' can be entered as \texttt{-} (hyphen) or \texttt{\char`\\\char`\<emdash\char`\>}.
   36.18 +of nonnegative integers (e.g., $1$--$4$). The range symbol `--' is entered as \texttt{-} (hyphen).
   36.19  \item[\labelitemi] \qtybf{int\_seq}: A comma-separated sequence of ranges of integers (e.g.,~1{,}3{,}\allowbreak6--8).
   36.20  \item[\labelitemi] \qtybf{float}: An floating-point number (e.g., 0.5 or 60)
   36.21  expressing a number of seconds.
    37.1 --- a/src/Doc/Sugar/Sugar.thy	Tue Nov 10 14:18:41 2015 +0000
    37.2 +++ b/src/Doc/Sugar/Sugar.thy	Tue Nov 10 14:43:29 2015 +0000
    37.3 @@ -137,7 +137,7 @@
    37.4  suppresses question marks; variables that end in digits,
    37.5  e.g. @{text"x1"}, are still printed with a trailing @{text".0"},
    37.6  e.g. @{text"x1.0"}, their internal index. This can be avoided by
    37.7 -turning the last digit into a subscript: write \verb!x\<^sub>1! and
    37.8 +turning the last digit into a subscript: write \<^verbatim>\<open>x\<^sub>1\<close> and
    37.9  obtain the much nicer @{text"x\<^sub>1"}. *}
   37.10  
   37.11  (*<*)declare [[show_question_marks = false]](*>*)
    38.1 --- a/src/Doc/System/Basics.thy	Tue Nov 10 14:18:41 2015 +0000
    38.2 +++ b/src/Doc/System/Basics.thy	Tue Nov 10 14:43:29 2015 +0000
    38.3 @@ -1,35 +1,34 @@
    38.4 +(*:wrap=hard:maxLineLen=78:*)
    38.5 +
    38.6  theory Basics
    38.7  imports Base
    38.8  begin
    38.9  
   38.10  chapter \<open>The Isabelle system environment\<close>
   38.11  
   38.12 -text \<open>This manual describes Isabelle together with related tools and
   38.13 -  user interfaces as seen from a system oriented view.  See also the
   38.14 -  \<^emph>\<open>Isabelle/Isar Reference Manual\<close> @{cite "isabelle-isar-ref"} for
   38.15 -  the actual Isabelle input language and related concepts, and
   38.16 -  \<^emph>\<open>The Isabelle/Isar Implementation
   38.17 +text \<open>
   38.18 +  This manual describes Isabelle together with related tools and user
   38.19 +  interfaces as seen from a system oriented view. See also the \<^emph>\<open>Isabelle/Isar
   38.20 +  Reference Manual\<close> @{cite "isabelle-isar-ref"} for the actual Isabelle input
   38.21 +  language and related concepts, and \<^emph>\<open>The Isabelle/Isar Implementation
   38.22    Manual\<close> @{cite "isabelle-implementation"} for the main concepts of the
   38.23    underlying implementation in Isabelle/ML.
   38.24  
   38.25    \<^medskip>
   38.26 -  The Isabelle system environment provides the following
   38.27 -  basic infrastructure to integrate tools smoothly.
   38.28 +  The Isabelle system environment provides the following basic infrastructure
   38.29 +  to integrate tools smoothly.
   38.30  
   38.31 -  \<^enum> The \<^emph>\<open>Isabelle settings\<close> mechanism provides process
   38.32 -  environment variables to all Isabelle executables (including tools
   38.33 -  and user interfaces).
   38.34 +  \<^enum> The \<^emph>\<open>Isabelle settings\<close> mechanism provides process environment variables
   38.35 +  to all Isabelle executables (including tools and user interfaces).
   38.36  
   38.37 -  \<^enum> The raw \<^emph>\<open>Isabelle process\<close> (@{executable_ref
   38.38 -  "isabelle_process"}) runs logic sessions either interactively or in
   38.39 -  batch mode.  In particular, this view abstracts over the invocation
   38.40 -  of the actual ML system to be used.  Regular users rarely need to
   38.41 -  care about the low-level process.
   38.42 +  \<^enum> The raw \<^emph>\<open>Isabelle process\<close> (@{executable_ref "isabelle_process"}) runs
   38.43 +  logic sessions either interactively or in batch mode. In particular, this
   38.44 +  view abstracts over the invocation of the actual ML system to be used.
   38.45 +  Regular users rarely need to care about the low-level process.
   38.46  
   38.47 -  \<^enum> The main \<^emph>\<open>Isabelle tool wrapper\<close> (@{executable_ref
   38.48 -  isabelle}) provides a generic startup environment Isabelle related
   38.49 -  utilities, user interfaces etc.  Such tools automatically benefit
   38.50 -  from the settings mechanism.
   38.51 +  \<^enum> The main \<^emph>\<open>Isabelle tool wrapper\<close> (@{executable_ref isabelle}) provides a
   38.52 +  generic startup environment Isabelle related utilities, user interfaces etc.
   38.53 +  Such tools automatically benefit from the settings mechanism.
   38.54  \<close>
   38.55  
   38.56  
   38.57 @@ -37,299 +36,270 @@
   38.58  
   38.59  text \<open>
   38.60    The Isabelle system heavily depends on the \<^emph>\<open>settings
   38.61 -  mechanism\<close>\indexbold{settings}.  Essentially, this is a statically
   38.62 -  scoped collection of environment variables, such as @{setting
   38.63 -  ISABELLE_HOME}, @{setting ML_SYSTEM}, @{setting ML_HOME}.  These
   38.64 -  variables are \<^emph>\<open>not\<close> intended to be set directly from the shell,
   38.65 -  though.  Isabelle employs a somewhat more sophisticated scheme of
   38.66 -  \<^emph>\<open>settings files\<close> --- one for site-wide defaults, another for
   38.67 -  additional user-specific modifications.  With all configuration
   38.68 -  variables in clearly defined places, this scheme is more
   38.69 -  maintainable and user-friendly than global shell environment
   38.70 -  variables.
   38.71 +  mechanism\<close>\indexbold{settings}. Essentially, this is a statically scoped
   38.72 +  collection of environment variables, such as @{setting ISABELLE_HOME},
   38.73 +  @{setting ML_SYSTEM}, @{setting ML_HOME}. These variables are \<^emph>\<open>not\<close>
   38.74 +  intended to be set directly from the shell, though. Isabelle employs a
   38.75 +  somewhat more sophisticated scheme of \<^emph>\<open>settings files\<close> --- one for
   38.76 +  site-wide defaults, another for additional user-specific modifications. With
   38.77 +  all configuration variables in clearly defined places, this scheme is more
   38.78 +  maintainable and user-friendly than global shell environment variables.
   38.79  
   38.80 -  In particular, we avoid the typical situation where prospective
   38.81 -  users of a software package are told to put several things into
   38.82 -  their shell startup scripts, before being able to actually run the
   38.83 -  program. Isabelle requires none such administrative chores of its
   38.84 -  end-users --- the executables can be invoked straight away.
   38.85 -  Occasionally, users would still want to put the @{file
   38.86 -  "$ISABELLE_HOME/bin"} directory into their shell's search path, but
   38.87 +  In particular, we avoid the typical situation where prospective users of a
   38.88 +  software package are told to put several things into their shell startup
   38.89 +  scripts, before being able to actually run the program. Isabelle requires
   38.90 +  none such administrative chores of its end-users --- the executables can be
   38.91 +  invoked straight away. Occasionally, users would still want to put the
   38.92 +  @{file "$ISABELLE_HOME/bin"} directory into their shell's search path, but
   38.93    this is not required.
   38.94  \<close>
   38.95  
   38.96  
   38.97  subsection \<open>Bootstrapping the environment \label{sec:boot}\<close>
   38.98  
   38.99 -text \<open>Isabelle executables need to be run within a proper settings
  38.100 -  environment.  This is bootstrapped as described below, on the first
  38.101 -  invocation of one of the outer wrapper scripts (such as
  38.102 -  @{executable_ref isabelle}).  This happens only once for each
  38.103 -  process tree, i.e.\ the environment is passed to subprocesses
  38.104 -  according to regular Unix conventions.
  38.105 +text \<open>
  38.106 +  Isabelle executables need to be run within a proper settings environment.
  38.107 +  This is bootstrapped as described below, on the first invocation of one of
  38.108 +  the outer wrapper scripts (such as @{executable_ref isabelle}). This happens
  38.109 +  only once for each process tree, i.e.\ the environment is passed to
  38.110 +  subprocesses according to regular Unix conventions.
  38.111 +
  38.112 +    \<^enum> The special variable @{setting_def ISABELLE_HOME} is determined
  38.113 +    automatically from the location of the binary that has been run.
  38.114  
  38.115 -  \<^enum> The special variable @{setting_def ISABELLE_HOME} is
  38.116 -  determined automatically from the location of the binary that has
  38.117 -  been run.
  38.118 -  
  38.119 -  You should not try to set @{setting ISABELLE_HOME} manually. Also
  38.120 -  note that the Isabelle executables either have to be run from their
  38.121 -  original location in the distribution directory, or via the
  38.122 -  executable objects created by the @{tool install} tool.  Symbolic
  38.123 -  links are admissible, but a plain copy of the @{file
  38.124 -  "$ISABELLE_HOME/bin"} files will not work!
  38.125 +    You should not try to set @{setting ISABELLE_HOME} manually. Also note
  38.126 +    that the Isabelle executables either have to be run from their original
  38.127 +    location in the distribution directory, or via the executable objects
  38.128 +    created by the @{tool install} tool. Symbolic links are admissible, but a
  38.129 +    plain copy of the @{file "$ISABELLE_HOME/bin"} files will not work!
  38.130 +
  38.131 +    \<^enum> The file @{file "$ISABELLE_HOME/etc/settings"} is run as a
  38.132 +    @{executable_ref bash} shell script with the auto-export option for
  38.133 +    variables enabled.
  38.134  
  38.135 -  \<^enum> The file @{file "$ISABELLE_HOME/etc/settings"} is run as a
  38.136 -  @{executable_ref bash} shell script with the auto-export option for
  38.137 -  variables enabled.
  38.138 -  
  38.139 -  This file holds a rather long list of shell variable assigments,
  38.140 -  thus providing the site-wide default settings.  The Isabelle
  38.141 -  distribution already contains a global settings file with sensible
  38.142 -  defaults for most variables.  When installing the system, only a few
  38.143 -  of these may have to be adapted (probably @{setting ML_SYSTEM}
  38.144 -  etc.).
  38.145 -  
  38.146 -  \<^enum> The file @{file_unchecked "$ISABELLE_HOME_USER/etc/settings"} (if it
  38.147 -  exists) is run in the same way as the site default settings. Note
  38.148 -  that the variable @{setting ISABELLE_HOME_USER} has already been set
  38.149 -  before --- usually to something like \<^verbatim>\<open>$USER_HOME/.isabelle/IsabelleXXXX\<close>.
  38.150 -  
  38.151 -  Thus individual users may override the site-wide defaults.
  38.152 -  Typically, a user settings file contains only a few lines, with some
  38.153 -  assignments that are actually changed.  Never copy the central
  38.154 -  @{file "$ISABELLE_HOME/etc/settings"} file!
  38.155 +    This file holds a rather long list of shell variable assignments, thus
  38.156 +    providing the site-wide default settings. The Isabelle distribution
  38.157 +    already contains a global settings file with sensible defaults for most
  38.158 +    variables. When installing the system, only a few of these may have to be
  38.159 +    adapted (probably @{setting ML_SYSTEM} etc.).
  38.160 +
  38.161 +    \<^enum> The file @{file_unchecked "$ISABELLE_HOME_USER/etc/settings"} (if it
  38.162 +    exists) is run in the same way as the site default settings. Note that the
  38.163 +    variable @{setting ISABELLE_HOME_USER} has already been set before ---
  38.164 +    usually to something like \<^verbatim>\<open>$USER_HOME/.isabelle/IsabelleXXXX\<close>.
  38.165  
  38.166 +    Thus individual users may override the site-wide defaults. Typically, a
  38.167 +    user settings file contains only a few lines, with some assignments that
  38.168 +    are actually changed. Never copy the central @{file
  38.169 +    "$ISABELLE_HOME/etc/settings"} file!
  38.170  
  38.171 -  Since settings files are regular GNU @{executable_def bash} scripts,
  38.172 -  one may use complex shell commands, such as \<^verbatim>\<open>if\<close> or
  38.173 -  \<^verbatim>\<open>case\<close> statements to set variables depending on the
  38.174 -  system architecture or other environment variables.  Such advanced
  38.175 -  features should be added only with great care, though. In
  38.176 -  particular, external environment references should be kept at a
  38.177 +  Since settings files are regular GNU @{executable_def bash} scripts, one may
  38.178 +  use complex shell commands, such as \<^verbatim>\<open>if\<close> or \<^verbatim>\<open>case\<close> statements to set
  38.179 +  variables depending on the system architecture or other environment
  38.180 +  variables. Such advanced features should be added only with great care,
  38.181 +  though. In particular, external environment references should be kept at a
  38.182    minimum.
  38.183  
  38.184    \<^medskip>
  38.185    A few variables are somewhat special:
  38.186  
  38.187 -  \<^item> @{setting_def ISABELLE_PROCESS} and @{setting_def ISABELLE_TOOL} are set
  38.188 -  automatically to the absolute path names of the @{executable
  38.189 -  "isabelle_process"} and @{executable isabelle} executables,
  38.190 -  respectively.
  38.191 -  
  38.192 -  \<^item> @{setting_ref ISABELLE_OUTPUT} will have the identifiers of
  38.193 -  the Isabelle distribution (cf.\ @{setting ISABELLE_IDENTIFIER}) and
  38.194 -  the ML system (cf.\ @{setting ML_IDENTIFIER}) appended automatically
  38.195 -  to its value.
  38.196 +    \<^item> @{setting_def ISABELLE_PROCESS} and @{setting_def ISABELLE_TOOL} are set
  38.197 +    automatically to the absolute path names of the @{executable
  38.198 +    "isabelle_process"} and @{executable isabelle} executables, respectively.
  38.199  
  38.200 +    \<^item> @{setting_ref ISABELLE_OUTPUT} will have the identifiers of the Isabelle
  38.201 +    distribution (cf.\ @{setting ISABELLE_IDENTIFIER}) and the ML system (cf.\
  38.202 +    @{setting ML_IDENTIFIER}) appended automatically to its value.
  38.203  
  38.204    \<^medskip>
  38.205 -  Note that the settings environment may be inspected with
  38.206 -  the @{tool getenv} tool.  This might help to figure out the effect
  38.207 -  of complex settings scripts.\<close>
  38.208 +  Note that the settings environment may be inspected with the @{tool getenv}
  38.209 +  tool. This might help to figure out the effect of complex settings scripts.
  38.210 +\<close>
  38.211  
  38.212  
  38.213  subsection \<open>Common variables\<close>
  38.214  
  38.215  text \<open>
  38.216 -  This is a reference of common Isabelle settings variables. Note that
  38.217 -  the list is somewhat open-ended. Third-party utilities or interfaces
  38.218 -  may add their own selection. Variables that are special in some
  38.219 -  sense are marked with \<open>\<^sup>*\<close>.
  38.220 +  This is a reference of common Isabelle settings variables. Note that the
  38.221 +  list is somewhat open-ended. Third-party utilities or interfaces may add
  38.222 +  their own selection. Variables that are special in some sense are marked
  38.223 +  with \<open>\<^sup>*\<close>.
  38.224  
  38.225 -  \<^descr>[@{setting_def USER_HOME}\<open>\<^sup>*\<close>] Is the cross-platform
  38.226 -  user home directory.  On Unix systems this is usually the same as
  38.227 -  @{setting HOME}, but on Windows it is the regular home directory of
  38.228 -  the user, not the one of within the Cygwin root
  38.229 -  file-system.\footnote{Cygwin itself offers another choice whether
  38.230 -  its HOME should point to the @{file_unchecked "/home"} directory tree or the
  38.231 -  Windows user home.}
  38.232 +  \<^descr>[@{setting_def USER_HOME}\<open>\<^sup>*\<close>] Is the cross-platform user home directory.
  38.233 +  On Unix systems this is usually the same as @{setting HOME}, but on Windows
  38.234 +  it is the regular home directory of the user, not the one of within the
  38.235 +  Cygwin root file-system.\<^footnote>\<open>Cygwin itself offers another choice whether its
  38.236 +  HOME should point to the @{file_unchecked "/home"} directory tree or the
  38.237 +  Windows user home.\<close>
  38.238  
  38.239 -  \<^descr>[@{setting_def ISABELLE_HOME}\<open>\<^sup>*\<close>] is the location of the
  38.240 -  top-level Isabelle distribution directory. This is automatically
  38.241 -  determined from the Isabelle executable that has been invoked.  Do
  38.242 -  not attempt to set @{setting ISABELLE_HOME} yourself from the shell!
  38.243 -  
  38.244 -  \<^descr>[@{setting_def ISABELLE_HOME_USER}] is the user-specific
  38.245 -  counterpart of @{setting ISABELLE_HOME}. The default value is
  38.246 -  relative to @{file_unchecked "$USER_HOME/.isabelle"}, under rare
  38.247 -  circumstances this may be changed in the global setting file.
  38.248 -  Typically, the @{setting ISABELLE_HOME_USER} directory mimics
  38.249 -  @{setting ISABELLE_HOME} to some extend. In particular, site-wide
  38.250 -  defaults may be overridden by a private
  38.251 -  \<^verbatim>\<open>$ISABELLE_HOME_USER/etc/settings\<close>.
  38.252 +  \<^descr>[@{setting_def ISABELLE_HOME}\<open>\<^sup>*\<close>] is the location of the top-level
  38.253 +  Isabelle distribution directory. This is automatically determined from the
  38.254 +  Isabelle executable that has been invoked. Do not attempt to set @{setting
  38.255 +  ISABELLE_HOME} yourself from the shell!
  38.256  
  38.257 -  \<^descr>[@{setting_def ISABELLE_PLATFORM_FAMILY}\<open>\<^sup>*\<close>] is
  38.258 -  automatically set to the general platform family: \<^verbatim>\<open>linux\<close>,
  38.259 -  \<^verbatim>\<open>macos\<close>, \<^verbatim>\<open>windows\<close>.  Note that
  38.260 +  \<^descr>[@{setting_def ISABELLE_HOME_USER}] is the user-specific counterpart of
  38.261 +  @{setting ISABELLE_HOME}. The default value is relative to @{file_unchecked
  38.262 +  "$USER_HOME/.isabelle"}, under rare circumstances this may be changed in the
  38.263 +  global setting file. Typically, the @{setting ISABELLE_HOME_USER} directory
  38.264 +  mimics @{setting ISABELLE_HOME} to some extend. In particular, site-wide
  38.265 +  defaults may be overridden by a private \<^verbatim>\<open>$ISABELLE_HOME_USER/etc/settings\<close>.
  38.266 +
  38.267 +  \<^descr>[@{setting_def ISABELLE_PLATFORM_FAMILY}\<open>\<^sup>*\<close>] is automatically set to the
  38.268 +  general platform family: \<^verbatim>\<open>linux\<close>, \<^verbatim>\<open>macos\<close>, \<^verbatim>\<open>windows\<close>. Note that
  38.269    platform-dependent tools usually need to refer to the more specific
  38.270    identification according to @{setting ISABELLE_PLATFORM}, @{setting
  38.271    ISABELLE_PLATFORM32}, @{setting ISABELLE_PLATFORM64}.
  38.272  
  38.273 -  \<^descr>[@{setting_def ISABELLE_PLATFORM}\<open>\<^sup>*\<close>] is automatically
  38.274 -  set to a symbolic identifier for the underlying hardware and
  38.275 -  operating system.  The Isabelle platform identification always
  38.276 -  refers to the 32 bit variant, even this is a 64 bit machine.  Note
  38.277 -  that the ML or Java runtime may have a different idea, depending on
  38.278 -  which binaries are actually run.
  38.279 +  \<^descr>[@{setting_def ISABELLE_PLATFORM}\<open>\<^sup>*\<close>] is automatically set to a symbolic
  38.280 +  identifier for the underlying hardware and operating system. The Isabelle
  38.281 +  platform identification always refers to the 32 bit variant, even this is a
  38.282 +  64 bit machine. Note that the ML or Java runtime may have a different idea,
  38.283 +  depending on which binaries are actually run.
  38.284  
  38.285 -  \<^descr>[@{setting_def ISABELLE_PLATFORM64}\<open>\<^sup>*\<close>] is similar to
  38.286 -  @{setting ISABELLE_PLATFORM} but refers to the proper 64 bit variant
  38.287 -  on a platform that supports this; the value is empty for 32 bit.
  38.288 -  Note that the following bash expression (including the quotes)
  38.289 -  prefers the 64 bit platform, if that is available:
  38.290 +  \<^descr>[@{setting_def ISABELLE_PLATFORM64}\<open>\<^sup>*\<close>] is similar to @{setting
  38.291 +  ISABELLE_PLATFORM} but refers to the proper 64 bit variant on a platform
  38.292 +  that supports this; the value is empty for 32 bit. Note that the following
  38.293 +  bash expression (including the quotes) prefers the 64 bit platform, if that
  38.294 +  is available:
  38.295  
  38.296    @{verbatim [display] \<open>"${ISABELLE_PLATFORM64:-$ISABELLE_PLATFORM}"\<close>}
  38.297  
  38.298 -  \<^descr>[@{setting_def ISABELLE_PROCESS}\<open>\<^sup>*\<close>, @{setting
  38.299 -  ISABELLE_TOOL}\<open>\<^sup>*\<close>] are automatically set to the full path
  38.300 -  names of the @{executable "isabelle_process"} and @{executable
  38.301 -  isabelle} executables, respectively.  Thus other tools and scripts
  38.302 -  need not assume that the @{file "$ISABELLE_HOME/bin"} directory is
  38.303 -  on the current search path of the shell.
  38.304 -  
  38.305 -  \<^descr>[@{setting_def ISABELLE_IDENTIFIER}\<open>\<^sup>*\<close>] refers
  38.306 -  to the name of this Isabelle distribution, e.g.\ ``\<^verbatim>\<open>Isabelle2012\<close>''.
  38.307 +  \<^descr>[@{setting_def ISABELLE_PROCESS}\<open>\<^sup>*\<close>, @{setting ISABELLE_TOOL}\<open>\<^sup>*\<close>] are
  38.308 +  automatically set to the full path names of the @{executable
  38.309 +  "isabelle_process"} and @{executable isabelle} executables, respectively.
  38.310 +  Thus other tools and scripts need not assume that the @{file
  38.311 +  "$ISABELLE_HOME/bin"} directory is on the current search path of the shell.
  38.312  
  38.313 -  \<^descr>[@{setting_def ML_SYSTEM}, @{setting_def ML_HOME},
  38.314 -  @{setting_def ML_OPTIONS}, @{setting_def ML_PLATFORM}, @{setting_def
  38.315 -  ML_IDENTIFIER}\<open>\<^sup>*\<close>] specify the underlying ML system
  38.316 -  to be used for Isabelle.  There is only a fixed set of admissable
  38.317 -  @{setting ML_SYSTEM} names (see the @{file
  38.318 +  \<^descr>[@{setting_def ISABELLE_IDENTIFIER}\<open>\<^sup>*\<close>] refers to the name of this
  38.319 +  Isabelle distribution, e.g.\ ``\<^verbatim>\<open>Isabelle2012\<close>''.
  38.320 +
  38.321 +  \<^descr>[@{setting_def ML_SYSTEM}, @{setting_def ML_HOME}, @{setting_def
  38.322 +  ML_OPTIONS}, @{setting_def ML_PLATFORM}, @{setting_def ML_IDENTIFIER}\<open>\<^sup>*\<close>]
  38.323 +  specify the underlying ML system to be used for Isabelle. There is only a
  38.324 +  fixed set of admissable @{setting ML_SYSTEM} names (see the @{file
  38.325    "$ISABELLE_HOME/etc/settings"} file of the distribution).
  38.326 -  
  38.327 +
  38.328    The actual compiler binary will be run from the directory @{setting
  38.329 -  ML_HOME}, with @{setting ML_OPTIONS} as first arguments on the
  38.330 -  command line.  The optional @{setting ML_PLATFORM} may specify the
  38.331 -  binary format of ML heap images, which is useful for cross-platform
  38.332 -  installations.  The value of @{setting ML_IDENTIFIER} is
  38.333 -  automatically obtained by composing the values of @{setting
  38.334 -  ML_SYSTEM}, @{setting ML_PLATFORM} and the Isabelle version values.
  38.335 +  ML_HOME}, with @{setting ML_OPTIONS} as first arguments on the command line.
  38.336 +  The optional @{setting ML_PLATFORM} may specify the binary format of ML heap
  38.337 +  images, which is useful for cross-platform installations. The value of
  38.338 +  @{setting ML_IDENTIFIER} is automatically obtained by composing the values
  38.339 +  of @{setting ML_SYSTEM}, @{setting ML_PLATFORM} and the Isabelle version
  38.340 +  values.
  38.341  
  38.342 -  \<^descr>[@{setting_def ML_SYSTEM_POLYML}\<open>\<^sup>*\<close>] is \<^verbatim>\<open>true\<close>
  38.343 -  for @{setting ML_SYSTEM} values derived from Poly/ML, as opposed to
  38.344 -  SML/NJ where it is empty.  This is particularly useful with the
  38.345 -  build option @{system_option condition}
  38.346 -  (\secref{sec:system-options}) to restrict big sessions to something
  38.347 -  that SML/NJ can still handle.
  38.348 +  \<^descr>[@{setting_def ML_SYSTEM_POLYML}\<open>\<^sup>*\<close>] is \<^verbatim>\<open>true\<close> for @{setting ML_SYSTEM}
  38.349 +  values derived from Poly/ML, as opposed to SML/NJ where it is empty. This is
  38.350 +  particularly useful with the build option @{system_option condition}
  38.351 +  (\secref{sec:system-options}) to restrict big sessions to something that
  38.352 +  SML/NJ can still handle.
  38.353  
  38.354 -  \<^descr>[@{setting_def ISABELLE_JDK_HOME}] needs to point to a full JDK
  38.355 -  (Java Development Kit) installation with \<^verbatim>\<open>javac\<close> and
  38.356 -  \<^verbatim>\<open>jar\<close> executables.  This is essential for Isabelle/Scala
  38.357 -  and other JVM-based tools to work properly.  Note that conventional
  38.358 -  \<^verbatim>\<open>JAVA_HOME\<close> usually points to the JRE (Java Runtime
  38.359 +  \<^descr>[@{setting_def ISABELLE_JDK_HOME}] needs to point to a full JDK (Java
  38.360 +  Development Kit) installation with \<^verbatim>\<open>javac\<close> and \<^verbatim>\<open>jar\<close> executables. This is
  38.361 +  essential for Isabelle/Scala and other JVM-based tools to work properly.
  38.362 +  Note that conventional \<^verbatim>\<open>JAVA_HOME\<close> usually points to the JRE (Java Runtime
  38.363    Environment), not JDK.
  38.364 -  
  38.365 -  \<^descr>[@{setting_def ISABELLE_PATH}] is a list of directories
  38.366 -  (separated by colons) where Isabelle logic images may reside.  When
  38.367 -  looking up heaps files, the value of @{setting ML_IDENTIFIER} is
  38.368 -  appended to each component internally.
  38.369 -  
  38.370 -  \<^descr>[@{setting_def ISABELLE_OUTPUT}\<open>\<^sup>*\<close>] is a
  38.371 -  directory where output heap files should be stored by default. The
  38.372 -  ML system and Isabelle version identifier is appended here, too.
  38.373 -  
  38.374 -  \<^descr>[@{setting_def ISABELLE_BROWSER_INFO}] is the directory where
  38.375 -  theory browser information (HTML text, graph data, and printable
  38.376 -  documents) is stored (see also \secref{sec:info}).  The default
  38.377 -  value is @{file_unchecked "$ISABELLE_HOME_USER/browser_info"}.
  38.378 -  
  38.379 -  \<^descr>[@{setting_def ISABELLE_LOGIC}] specifies the default logic to
  38.380 -  load if none is given explicitely by the user.  The default value is
  38.381 -  \<^verbatim>\<open>HOL\<close>.
  38.382 -  
  38.383 -  \<^descr>[@{setting_def ISABELLE_LINE_EDITOR}] specifies the
  38.384 -  line editor for the @{tool_ref console} interface.
  38.385 +
  38.386 +  \<^descr>[@{setting_def ISABELLE_PATH}] is a list of directories (separated by
  38.387 +  colons) where Isabelle logic images may reside. When looking up heaps files,
  38.388 +  the value of @{setting ML_IDENTIFIER} is appended to each component
  38.389 +  internally.
  38.390 +
  38.391 +  \<^descr>[@{setting_def ISABELLE_OUTPUT}\<open>\<^sup>*\<close>] is a directory where output heap files
  38.392 +  should be stored by default. The ML system and Isabelle version identifier
  38.393 +  is appended here, too.
  38.394 +
  38.395 +  \<^descr>[@{setting_def ISABELLE_BROWSER_INFO}] is the directory where theory
  38.396 +  browser information (HTML text, graph data, and printable documents) is
  38.397 +  stored (see also \secref{sec:info}). The default value is @{file_unchecked
  38.398 +  "$ISABELLE_HOME_USER/browser_info"}.
  38.399 +
  38.400 +  \<^descr>[@{setting_def ISABELLE_LOGIC}] specifies the default logic to load if none
  38.401 +  is given explicitely by the user. The default value is \<^verbatim>\<open>HOL\<close>.
  38.402 +
  38.403 +  \<^descr>[@{setting_def ISABELLE_LINE_EDITOR}] specifies the line editor for the
  38.404 +  @{tool_ref console} interface.
  38.405  
  38.406 -  \<^descr>[@{setting_def ISABELLE_LATEX}, @{setting_def
  38.407 -  ISABELLE_PDFLATEX}, @{setting_def ISABELLE_BIBTEX}] refer to {\LaTeX}
  38.408 -  related tools for Isabelle document preparation (see also
  38.409 -  \secref{sec:tool-latex}).
  38.410 -  
  38.411 -  \<^descr>[@{setting_def ISABELLE_TOOLS}] is a colon separated list of
  38.412 -  directories that are scanned by @{executable isabelle} for external
  38.413 -  utility programs (see also \secref{sec:isabelle-tool}).
  38.414 -  
  38.415 -  \<^descr>[@{setting_def ISABELLE_DOCS}] is a colon separated list of
  38.416 -  directories with documentation files.
  38.417 +  \<^descr>[@{setting_def ISABELLE_LATEX}, @{setting_def ISABELLE_PDFLATEX},
  38.418 +  @{setting_def ISABELLE_BIBTEX}] refer to {\LaTeX} related tools for Isabelle
  38.419 +  document preparation (see also \secref{sec:tool-latex}).
  38.420 +
  38.421 +  \<^descr>[@{setting_def ISABELLE_TOOLS}] is a colon separated list of directories
  38.422 +  that are scanned by @{executable isabelle} for external utility programs
  38.423 +  (see also \secref{sec:isabelle-tool}).
  38.424  
  38.425 -  \<^descr>[@{setting_def PDF_VIEWER}] specifies the program to be used
  38.426 -  for displaying \<^verbatim>\<open>pdf\<close> files.
  38.427 +  \<^descr>[@{setting_def ISABELLE_DOCS}] is a colon separated list of directories
  38.428 +  with documentation files.
  38.429 +
  38.430 +  \<^descr>[@{setting_def PDF_VIEWER}] specifies the program to be used for displaying
  38.431 +  \<^verbatim>\<open>pdf\<close> files.
  38.432  
  38.433 -  \<^descr>[@{setting_def DVI_VIEWER}] specifies the program to be used
  38.434 -  for displaying \<^verbatim>\<open>dvi\<close> files.
  38.435 -  
  38.436 -  \<^descr>[@{setting_def ISABELLE_TMP_PREFIX}\<open>\<^sup>*\<close>] is the
  38.437 -  prefix from which any running @{executable "isabelle_process"}
  38.438 -  derives an individual directory for temporary files.
  38.439 +  \<^descr>[@{setting_def DVI_VIEWER}] specifies the program to be used for displaying
  38.440 +  \<^verbatim>\<open>dvi\<close> files.
  38.441 +
  38.442 +  \<^descr>[@{setting_def ISABELLE_TMP_PREFIX}\<open>\<^sup>*\<close>] is the prefix from which any
  38.443 +  running @{executable "isabelle_process"} derives an individual directory for
  38.444 +  temporary files.
  38.445  \<close>
  38.446  
  38.447  
  38.448  subsection \<open>Additional components \label{sec:components}\<close>
  38.449  
  38.450 -text \<open>Any directory may be registered as an explicit \<^emph>\<open>Isabelle
  38.451 -  component\<close>.  The general layout conventions are that of the main
  38.452 -  Isabelle distribution itself, and the following two files (both
  38.453 -  optional) have a special meaning:
  38.454 +text \<open>
  38.455 +  Any directory may be registered as an explicit \<^emph>\<open>Isabelle component\<close>. The
  38.456 +  general layout conventions are that of the main Isabelle distribution
  38.457 +  itself, and the following two files (both optional) have a special meaning:
  38.458  
  38.459 -  \<^item> \<^verbatim>\<open>etc/settings\<close> holds additional settings that are
  38.460 -  initialized when bootstrapping the overall Isabelle environment,
  38.461 -  cf.\ \secref{sec:boot}.  As usual, the content is interpreted as a
  38.462 -  \<^verbatim>\<open>bash\<close> script.  It may refer to the component's enclosing
  38.463 -  directory via the \<^verbatim>\<open>COMPONENT\<close> shell variable.
  38.464 +    \<^item> \<^verbatim>\<open>etc/settings\<close> holds additional settings that are initialized when
  38.465 +    bootstrapping the overall Isabelle environment, cf.\ \secref{sec:boot}. As
  38.466 +    usual, the content is interpreted as a \<^verbatim>\<open>bash\<close> script. It may refer to the
  38.467 +    component's enclosing directory via the \<^verbatim>\<open>COMPONENT\<close> shell variable.
  38.468  
  38.469 -  For example, the following setting allows to refer to files within
  38.470 -  the component later on, without having to hardwire absolute paths:
  38.471 -  @{verbatim [display] \<open>MY_COMPONENT_HOME="$COMPONENT"\<close>}
  38.472 +    For example, the following setting allows to refer to files within the
  38.473 +    component later on, without having to hardwire absolute paths:
  38.474 +    @{verbatim [display] \<open>MY_COMPONENT_HOME="$COMPONENT"\<close>}
  38.475  
  38.476 -  Components can also add to existing Isabelle settings such as
  38.477 -  @{setting_def ISABELLE_TOOLS}, in order to provide
  38.478 -  component-specific tools that can be invoked by end-users.  For
  38.479 -  example:
  38.480 -  @{verbatim [display] \<open>ISABELLE_TOOLS="$ISABELLE_TOOLS:$COMPONENT/lib/Tools"\<close>}
  38.481 +    Components can also add to existing Isabelle settings such as
  38.482 +    @{setting_def ISABELLE_TOOLS}, in order to provide component-specific
  38.483 +    tools that can be invoked by end-users. For example:
  38.484 +    @{verbatim [display] \<open>ISABELLE_TOOLS="$ISABELLE_TOOLS:$COMPONENT/lib/Tools"\<close>}
  38.485  
  38.486 -  \<^item> \<^verbatim>\<open>etc/components\<close> holds a list of further
  38.487 -  sub-components of the same structure.  The directory specifications
  38.488 -  given here can be either absolute (with leading \<^verbatim>\<open>/\<close>) or
  38.489 -  relative to the component's main directory.
  38.490 +    \<^item> \<^verbatim>\<open>etc/components\<close> holds a list of further sub-components of the same
  38.491 +    structure. The directory specifications given here can be either absolute
  38.492 +    (with leading \<^verbatim>\<open>/\<close>) or relative to the component's main directory.
  38.493  
  38.494 -
  38.495 -  The root of component initialization is @{setting ISABELLE_HOME}
  38.496 -  itself.  After initializing all of its sub-components recursively,
  38.497 -  @{setting ISABELLE_HOME_USER} is included in the same manner (if
  38.498 -  that directory exists).  This allows to install private components
  38.499 -  via @{file_unchecked "$ISABELLE_HOME_USER/etc/components"}, although it is
  38.500 -  often more convenient to do that programmatically via the
  38.501 -  \<^verbatim>\<open>init_component\<close> shell function in the \<^verbatim>\<open>etc/settings\<close>
  38.502 -  script of \<^verbatim>\<open>$ISABELLE_HOME_USER\<close> (or any other component
  38.503 -  directory).  For example:
  38.504 +  The root of component initialization is @{setting ISABELLE_HOME} itself.
  38.505 +  After initializing all of its sub-components recursively, @{setting
  38.506 +  ISABELLE_HOME_USER} is included in the same manner (if that directory
  38.507 +  exists). This allows to install private components via @{file_unchecked
  38.508 +  "$ISABELLE_HOME_USER/etc/components"}, although it is often more convenient
  38.509 +  to do that programmatically via the \<^verbatim>\<open>init_component\<close> shell function in the
  38.510 +  \<^verbatim>\<open>etc/settings\<close> script of \<^verbatim>\<open>$ISABELLE_HOME_USER\<close> (or any other component
  38.511 +  directory). For example:
  38.512    @{verbatim [display] \<open>init_component "$HOME/screwdriver-2.0"\<close>}
  38.513  
  38.514 -  This is tolerant wrt.\ missing component directories, but might
  38.515 -  produce a warning.
  38.516 +  This is tolerant wrt.\ missing component directories, but might produce a
  38.517 +  warning.
  38.518  
  38.519    \<^medskip>
  38.520 -  More complex situations may be addressed by initializing
  38.521 -  components listed in a given catalog file, relatively to some base
  38.522 -  directory:
  38.523 +  More complex situations may be addressed by initializing components listed
  38.524 +  in a given catalog file, relatively to some base directory:
  38.525    @{verbatim [display] \<open>init_components "$HOME/my_component_store" "some_catalog_file"\<close>}
  38.526  
  38.527 -  The component directories listed in the catalog file are treated as
  38.528 -  relative to the given base directory.
  38.529 +  The component directories listed in the catalog file are treated as relative
  38.530 +  to the given base directory.
  38.531  
  38.532 -  See also \secref{sec:tool-components} for some tool-support for
  38.533 -  resolving components that are formally initialized but not installed
  38.534 -  yet.
  38.535 +  See also \secref{sec:tool-components} for some tool-support for resolving
  38.536 +  components that are formally initialized but not installed yet.
  38.537  \<close>
  38.538  
  38.539  
  38.540  section \<open>The raw Isabelle process \label{sec:isabelle-process}\<close>
  38.541  
  38.542  text \<open>
  38.543 -  The @{executable_def "isabelle_process"} executable runs bare-bones
  38.544 -  Isabelle logic sessions --- either interactively or in batch mode.
  38.545 -  It provides an abstraction over the underlying ML system, and over
  38.546 -  the actual heap file locations.  Its usage is:
  38.547 +  The @{executable_def "isabelle_process"} executable runs bare-bones Isabelle
  38.548 +  logic sessions --- either interactively or in batch mode. It provides an
  38.549 +  abstraction over the underlying ML system, and over the actual heap file
  38.550 +  locations. Its usage is:
  38.551    @{verbatim [display]
  38.552  \<open>Usage: isabelle_process [OPTIONS] [INPUT] [OUTPUT]
  38.553  
  38.554 @@ -349,123 +319,111 @@
  38.555    actual file names (containing at least one /).
  38.556    If INPUT is "RAW_ML_SYSTEM", just start the bare bones ML system.\<close>}
  38.557  
  38.558 -  Input files without path specifications are looked up in the
  38.559 -  @{setting ISABELLE_PATH} setting, which may consist of multiple
  38.560 -  components separated by colons --- these are tried in the given
  38.561 -  order with the value of @{setting ML_IDENTIFIER} appended
  38.562 -  internally.  In a similar way, base names are relative to the
  38.563 -  directory specified by @{setting ISABELLE_OUTPUT}.  In any case,
  38.564 -  actual file locations may also be given by including at least one
  38.565 -  slash (\<^verbatim>\<open>/\<close>) in the name (hint: use \<^verbatim>\<open>./\<close> to
  38.566 -  refer to the current directory).
  38.567 +  Input files without path specifications are looked up in the @{setting
  38.568 +  ISABELLE_PATH} setting, which may consist of multiple components separated
  38.569 +  by colons --- these are tried in the given order with the value of @{setting
  38.570 +  ML_IDENTIFIER} appended internally. In a similar way, base names are
  38.571 +  relative to the directory specified by @{setting ISABELLE_OUTPUT}. In any
  38.572 +  case, actual file locations may also be given by including at least one
  38.573 +  slash (\<^verbatim>\<open>/\<close>) in the name (hint: use \<^verbatim>\<open>./\<close> to refer to the current
  38.574 +  directory).
  38.575  \<close>
  38.576  
  38.577  
  38.578  subsubsection \<open>Options\<close>
  38.579  
  38.580  text \<open>
  38.581 -  If the input heap file does not have write permission bits set, or
  38.582 -  the \<^verbatim>\<open>-r\<close> option is given explicitly, then the session
  38.583 -  started will be read-only.  That is, the ML world cannot be
  38.584 -  committed back into the image file.  Otherwise, a writable session
  38.585 -  enables commits into either the input file, or into another output
  38.586 -  heap file (if that is given as the second argument on the command
  38.587 +  If the input heap file does not have write permission bits set, or the \<^verbatim>\<open>-r\<close>
  38.588 +  option is given explicitly, then the session started will be read-only. That
  38.589 +  is, the ML world cannot be committed back into the image file. Otherwise, a
  38.590 +  writable session enables commits into either the input file, or into another
  38.591 +  output heap file (if that is given as the second argument on the command
  38.592    line).
  38.593  
  38.594 -  The read-write state of sessions is determined at startup only, it
  38.595 -  cannot be changed intermediately. Also note that heap images may
  38.596 -  require considerable amounts of disk space (hundreds of MB or some GB).
  38.597 -  Users are responsible for themselves to dispose their heap files
  38.598 -  when they are no longer needed.
  38.599 +  The read-write state of sessions is determined at startup only, it cannot be
  38.600 +  changed intermediately. Also note that heap images may require considerable
  38.601 +  amounts of disk space (hundreds of MB or some GB). Users are responsible for
  38.602 +  themselves to dispose their heap files when they are no longer needed.
  38.603  
  38.604    \<^medskip>
  38.605 -  The \<^verbatim>\<open>-w\<close> option makes the output heap file
  38.606 -  read-only after terminating.  Thus subsequent invocations cause the
  38.607 -  logic image to be read-only automatically.
  38.608 +  The \<^verbatim>\<open>-w\<close> option makes the output heap file read-only after terminating.
  38.609 +  Thus subsequent invocations cause the logic image to be read-only
  38.610 +  automatically.
  38.611  
  38.612    \<^medskip>
  38.613 -  Using the \<^verbatim>\<open>-e\<close> option, arbitrary ML code may be
  38.614 -  passed to the Isabelle session from the command line. Multiple
  38.615 -  \<^verbatim>\<open>-e\<close> options are evaluated in the given order. Strange things
  38.616 -  may happen when erroneous ML code is provided. Also make sure that
  38.617 -  the ML commands are terminated properly by semicolon.
  38.618 +  Using the \<^verbatim>\<open>-e\<close> option, arbitrary ML code may be passed to the Isabelle
  38.619 +  session from the command line. Multiple \<^verbatim>\<open>-e\<close> options are evaluated in the
  38.620 +  given order. Strange things may happen when erroneous ML code is provided.
  38.621 +  Also make sure that the ML commands are terminated properly by semicolon.
  38.622  
  38.623    \<^medskip>
  38.624 -  The \<^verbatim>\<open>-m\<close> option adds identifiers of print modes
  38.625 -  to be made active for this session. Typically, this is used by some
  38.626 -  user interface, e.g.\ to enable output of proper mathematical
  38.627 -  symbols.
  38.628 +  The \<^verbatim>\<open>-m\<close> option adds identifiers of print modes to be made active for this
  38.629 +  session. Typically, this is used by some user interface, e.g.\ to enable
  38.630 +  output of proper mathematical symbols.
  38.631  
  38.632    \<^medskip>
  38.633 -  Isabelle normally enters an interactive top-level loop
  38.634 -  (after processing the \<^verbatim>\<open>-e\<close> texts). The \<^verbatim>\<open>-q\<close>
  38.635 -  option inhibits interaction, thus providing a pure batch mode
  38.636 -  facility.
  38.637 +  Isabelle normally enters an interactive top-level loop (after processing the
  38.638 +  \<^verbatim>\<open>-e\<close> texts). The \<^verbatim>\<open>-q\<close> option inhibits interaction, thus providing a pure
  38.639 +  batch mode facility.
  38.640  
  38.641    \<^medskip>
  38.642 -  Option \<^verbatim>\<open>-o\<close> allows to override Isabelle system
  38.643 -  options for this process, see also \secref{sec:system-options}.
  38.644 -  Alternatively, option \<^verbatim>\<open>-O\<close> specifies the full environment of
  38.645 -  system options as a file in YXML format (according to the Isabelle/Scala
  38.646 -  function \<^verbatim>\<open>isabelle.Options.encode\<close>).
  38.647 +  Option \<^verbatim>\<open>-o\<close> allows to override Isabelle system options for this process,
  38.648 +  see also \secref{sec:system-options}. Alternatively, option \<^verbatim>\<open>-O\<close> specifies
  38.649 +  the full environment of system options as a file in YXML format (according
  38.650 +  to the Isabelle/Scala function \<^verbatim>\<open>isabelle.Options.encode\<close>).
  38.651  
  38.652    \<^medskip>
  38.653 -  The \<^verbatim>\<open>-P\<close> option starts the Isabelle process wrapper
  38.654 -  for Isabelle/Scala, with a private protocol running over the specified TCP
  38.655 -  socket. Isabelle/ML and Isabelle/Scala provide various programming
  38.656 -  interfaces to invoke protocol functions over untyped strings and XML
  38.657 -  trees.
  38.658 +  The \<^verbatim>\<open>-P\<close> option starts the Isabelle process wrapper for Isabelle/Scala,
  38.659 +  with a private protocol running over the specified TCP socket. Isabelle/ML
  38.660 +  and Isabelle/Scala provide various programming interfaces to invoke protocol
  38.661 +  functions over untyped strings and XML trees.
  38.662  
  38.663    \<^medskip>
  38.664 -  The \<^verbatim>\<open>-S\<close> option makes the Isabelle process more
  38.665 -  secure by disabling some critical operations, notably runtime
  38.666 -  compilation and evaluation of ML source code.
  38.667 +  The \<^verbatim>\<open>-S\<close> option makes the Isabelle process more secure by disabling some
  38.668 +  critical operations, notably runtime compilation and evaluation of ML source
  38.669 +  code.
  38.670  \<close>
  38.671  
  38.672  
  38.673  subsubsection \<open>Examples\<close>
  38.674  
  38.675  text \<open>
  38.676 -  Run an interactive session of the default object-logic (as specified
  38.677 -  by the @{setting ISABELLE_LOGIC} setting) like this:
  38.678 +  Run an interactive session of the default object-logic (as specified by the
  38.679 +  @{setting ISABELLE_LOGIC} setting) like this:
  38.680    @{verbatim [display] \<open>isabelle_process\<close>}
  38.681  
  38.682 -  Usually @{setting ISABELLE_LOGIC} refers to one of the standard
  38.683 -  logic images, which are read-only by default.  A writable session
  38.684 -  --- based on \<^verbatim>\<open>HOL\<close>, but output to \<^verbatim>\<open>Test\<close> (in the
  38.685 -  directory specified by the @{setting ISABELLE_OUTPUT} setting) ---
  38.686 -  may be invoked as follows:
  38.687 +  Usually @{setting ISABELLE_LOGIC} refers to one of the standard logic
  38.688 +  images, which are read-only by default. A writable session --- based on
  38.689 +  \<^verbatim>\<open>HOL\<close>, but output to \<^verbatim>\<open>Test\<close> (in the directory specified by the @{setting
  38.690 +  ISABELLE_OUTPUT} setting) --- may be invoked as follows:
  38.691    @{verbatim [display] \<open>isabelle_process HOL Test\<close>}
  38.692  
  38.693 -  Ending this session normally (e.g.\ by typing control-D) dumps the
  38.694 -  whole ML system state into \<^verbatim>\<open>Test\<close> (be prepared for more
  38.695 -  than 100\,MB):
  38.696 +  Ending this session normally (e.g.\ by typing control-D) dumps the whole ML
  38.697 +  system state into \<^verbatim>\<open>Test\<close> (be prepared for more than 100\,MB):
  38.698  
  38.699 -  The \<^verbatim>\<open>Test\<close> session may be continued later (still in
  38.700 -  writable state) by: @{verbatim [display] \<open>isabelle_process Test\<close>}
  38.701 +  The \<^verbatim>\<open>Test\<close> session may be continued later (still in writable state) by:
  38.702 +  @{verbatim [display] \<open>isabelle_process Test\<close>}
  38.703  
  38.704    A read-only \<^verbatim>\<open>Test\<close> session may be started by:
  38.705    @{verbatim [display] \<open>isabelle_process -r Test\<close>}
  38.706  
  38.707    \<^bigskip>
  38.708 -  The next example demonstrates batch execution of Isabelle.
  38.709 -  We retrieve the \<^verbatim>\<open>Main\<close> theory value from the theory loader
  38.710 -  within ML (observe the delicate quoting rules for the Bash shell
  38.711 -  vs.\ ML):
  38.712 +  The next example demonstrates batch execution of Isabelle. We retrieve the
  38.713 +  \<^verbatim>\<open>Main\<close> theory value from the theory loader within ML (observe the delicate
  38.714 +  quoting rules for the Bash shell vs.\ ML):
  38.715    @{verbatim [display] \<open>isabelle_process -e 'Thy_Info.get_theory "Main";' -q -r HOL\<close>}
  38.716  
  38.717 -  Note that the output text will be interspersed with additional junk
  38.718 -  messages by the ML runtime environment.  The \<^verbatim>\<open>-W\<close> option
  38.719 -  allows to communicate with the Isabelle process via an external
  38.720 -  program in a more robust fashion.
  38.721 +  Note that the output text will be interspersed with additional junk messages
  38.722 +  by the ML runtime environment. The \<^verbatim>\<open>-W\<close> option allows to communicate with
  38.723 +  the Isabelle process via an external program in a more robust fashion.
  38.724  \<close>
  38.725  
  38.726  
  38.727  section \<open>The Isabelle tool wrapper \label{sec:isabelle-tool}\<close>
  38.728  
  38.729  text \<open>
  38.730 -  All Isabelle related tools and interfaces are called via a common
  38.731 -  wrapper --- @{executable isabelle}:
  38.732 +  All Isabelle related tools and interfaces are called via a common wrapper
  38.733 +  --- @{executable isabelle}:
  38.734    @{verbatim [display]
  38.735  \<open>Usage: isabelle TOOL [ARGS ...]
  38.736  
  38.737 @@ -474,20 +432,19 @@
  38.738  Available tools:
  38.739    ...\<close>}
  38.740  
  38.741 -  In principle, Isabelle tools are ordinary executable scripts that
  38.742 -  are run within the Isabelle settings environment, see
  38.743 -  \secref{sec:settings}.  The set of available tools is collected by
  38.744 -  @{executable isabelle} from the directories listed in the @{setting
  38.745 -  ISABELLE_TOOLS} setting.  Do not try to call the scripts directly
  38.746 -  from the shell.  Neither should you add the tool directories to your
  38.747 -  shell's search path!
  38.748 +  In principle, Isabelle tools are ordinary executable scripts that are run
  38.749 +  within the Isabelle settings environment, see \secref{sec:settings}. The set
  38.750 +  of available tools is collected by @{executable isabelle} from the
  38.751 +  directories listed in the @{setting ISABELLE_TOOLS} setting. Do not try to
  38.752 +  call the scripts directly from the shell. Neither should you add the tool
  38.753 +  directories to your shell's search path!
  38.754  \<close>
  38.755  
  38.756  
  38.757  subsubsection \<open>Examples\<close>
  38.758  
  38.759 -text \<open>Show the list of available documentation of the Isabelle
  38.760 -  distribution:
  38.761 +text \<open>
  38.762 +  Show the list of available documentation of the Isabelle distribution:
  38.763    @{verbatim [display] \<open>isabelle doc\<close>}
  38.764  
  38.765    View a certain document as follows:
    39.1 --- a/src/Doc/System/Misc.thy	Tue Nov 10 14:18:41 2015 +0000
    39.2 +++ b/src/Doc/System/Misc.thy	Tue Nov 10 14:43:29 2015 +0000
    39.3 @@ -1,3 +1,5 @@
    39.4 +(*:wrap=hard:maxLineLen=78:*)
    39.5 +
    39.6  theory Misc
    39.7  imports Base
    39.8  begin
    39.9 @@ -5,25 +7,27 @@
   39.10  chapter \<open>Miscellaneous tools \label{ch:tools}\<close>
   39.11  
   39.12  text \<open>
   39.13 -  Subsequently we describe various Isabelle related utilities, given
   39.14 -  in alphabetical order.
   39.15 +  Subsequently we describe various Isabelle related utilities, given in
   39.16 +  alphabetical order.
   39.17  \<close>
   39.18  
   39.19  
   39.20  section \<open>Theory graph browser \label{sec:browse}\<close>
   39.21  
   39.22 -text \<open>The Isabelle graph browser is a general tool for visualizing
   39.23 -  dependency graphs.  Certain nodes of the graph (i.e.\ theories) can
   39.24 -  be grouped together in ``directories'', whose contents may be
   39.25 -  hidden, thus enabling the user to collapse irrelevant portions of
   39.26 -  information.  The browser is written in Java, it can be used both as
   39.27 -  a stand-alone application and as an applet.\<close>
   39.28 +text \<open>
   39.29 +  The Isabelle graph browser is a general tool for visualizing dependency
   39.30 +  graphs. Certain nodes of the graph (i.e.\ theories) can be grouped together
   39.31 +  in ``directories'', whose contents may be hidden, thus enabling the user to
   39.32 +  collapse irrelevant portions of information. The browser is written in Java,
   39.33 +  it can be used both as a stand-alone application and as an applet.
   39.34 +\<close>
   39.35  
   39.36  
   39.37  subsection \<open>Invoking the graph browser\<close>
   39.38  
   39.39 -text \<open>The stand-alone version of the graph browser is wrapped up as
   39.40 -  @{tool_def browser}:
   39.41 +text \<open>
   39.42 +  The stand-alone version of the graph browser is wrapped up as @{tool_def
   39.43 +  browser}:
   39.44    @{verbatim [display]
   39.45  \<open>Usage: isabelle browser [OPTIONS] [GRAPHFILE]
   39.46  
   39.47 @@ -32,35 +36,31 @@
   39.48      -c           cleanup -- remove GRAPHFILE after use
   39.49      -o FILE      output to FILE (ps, eps, pdf)\<close>}
   39.50  
   39.51 -  When no file name is specified, the browser automatically changes to
   39.52 -  the directory @{setting ISABELLE_BROWSER_INFO}.
   39.53 +  When no file name is specified, the browser automatically changes to the
   39.54 +  directory @{setting ISABELLE_BROWSER_INFO}.
   39.55  
   39.56    \<^medskip>
   39.57 -  The \<^verbatim>\<open>-b\<close> option indicates that this is for
   39.58 -  administrative build only, i.e.\ no browser popup if no files are
   39.59 -  given.
   39.60 +  The \<^verbatim>\<open>-b\<close> option indicates that this is for administrative build only, i.e.\
   39.61 +  no browser popup if no files are given.
   39.62  
   39.63 -  The \<^verbatim>\<open>-c\<close> option causes the input file to be removed
   39.64 -  after use.
   39.65 +  The \<^verbatim>\<open>-c\<close> option causes the input file to be removed after use.
   39.66  
   39.67 -  The \<^verbatim>\<open>-o\<close> option indicates batch-mode operation, with the
   39.68 -  output written to the indicated file; note that \<^verbatim>\<open>pdf\<close>
   39.69 -  produces an \<^verbatim>\<open>eps\<close> copy as well.
   39.70 +  The \<^verbatim>\<open>-o\<close> option indicates batch-mode operation, with the output written to
   39.71 +  the indicated file; note that \<^verbatim>\<open>pdf\<close> produces an \<^verbatim>\<open>eps\<close> copy as well.
   39.72  
   39.73    \<^medskip>
   39.74 -  The applet version of the browser is part of the standard
   39.75 -  WWW theory presentation, see the link ``theory dependencies'' within
   39.76 -  each session index.
   39.77 +  The applet version of the browser is part of the standard WWW theory
   39.78 +  presentation, see the link ``theory dependencies'' within each session
   39.79 +  index.
   39.80  \<close>
   39.81  
   39.82  
   39.83  subsection \<open>Using the graph browser\<close>
   39.84  
   39.85  text \<open>
   39.86 -  The browser's main window, which is shown in
   39.87 -  \figref{fig:browserwindow}, consists of two sub-windows.  In the
   39.88 -  left sub-window, the directory tree is displayed. The graph itself
   39.89 -  is displayed in the right sub-window.
   39.90 +  The browser's main window, which is shown in \figref{fig:browserwindow},
   39.91 +  consists of two sub-windows. In the left sub-window, the directory tree is
   39.92 +  displayed. The graph itself is displayed in the right sub-window.
   39.93  
   39.94    \begin{figure}[ht]
   39.95    \includegraphics[width=\textwidth]{browser_screenshot}
   39.96 @@ -72,63 +72,57 @@
   39.97  subsubsection \<open>The directory tree window\<close>
   39.98  
   39.99  text \<open>
  39.100 -  We describe the usage of the directory browser and the meaning of
  39.101 -  the different items in the browser window.
  39.102 +  We describe the usage of the directory browser and the meaning of the
  39.103 +  different items in the browser window.
  39.104  
  39.105 -  \<^item> A red arrow before a directory name indicates that the
  39.106 -  directory is currently ``folded'', i.e.~the nodes in this directory
  39.107 -  are collapsed to one single node. In the right sub-window, the names
  39.108 -  of nodes corresponding to folded directories are enclosed in square
  39.109 -  brackets and displayed in red color.
  39.110 +  \<^item> A red arrow before a directory name indicates that the directory is
  39.111 +  currently ``folded'', i.e.~the nodes in this directory are collapsed to one
  39.112 +  single node. In the right sub-window, the names of nodes corresponding to
  39.113 +  folded directories are enclosed in square brackets and displayed in red
  39.114 +  color.
  39.115  
  39.116 -  \<^item> A green downward arrow before a directory name indicates that
  39.117 -  the directory is currently ``unfolded''. It can be folded by
  39.118 -  clicking on the directory name.  Clicking on the name for a second
  39.119 -  time unfolds the directory again.  Alternatively, a directory can
  39.120 -  also be unfolded by clicking on the corresponding node in the right
  39.121 -  sub-window.
  39.122 +  \<^item> A green downward arrow before a directory name indicates that the
  39.123 +  directory is currently ``unfolded''. It can be folded by clicking on the
  39.124 +  directory name. Clicking on the name for a second time unfolds the directory
  39.125 +  again. Alternatively, a directory can also be unfolded by clicking on the
  39.126 +  corresponding node in the right sub-window.
  39.127  
  39.128 -  \<^item> Blue arrows stand before ordinary node names. When clicking on
  39.129 -  such a name (i.e.\ that of a theory), the graph display window
  39.130 -  focuses to the corresponding node. Double clicking invokes a text
  39.131 -  viewer window in which the contents of the theory file are
  39.132 -  displayed.
  39.133 +  \<^item> Blue arrows stand before ordinary node names. When clicking on such a name
  39.134 +  (i.e.\ that of a theory), the graph display window focuses to the
  39.135 +  corresponding node. Double clicking invokes a text viewer window in which
  39.136 +  the contents of the theory file are displayed.
  39.137  \<close>
  39.138  
  39.139  
  39.140  subsubsection \<open>The graph display window\<close>
  39.141  
  39.142  text \<open>
  39.143 -  When pointing on an ordinary node, an upward and a downward arrow is
  39.144 -  shown.  Initially, both of these arrows are green. Clicking on the
  39.145 -  upward or downward arrow collapses all predecessor or successor
  39.146 -  nodes, respectively. The arrow's color then changes to red,
  39.147 -  indicating that the predecessor or successor nodes are currently
  39.148 -  collapsed. The node corresponding to the collapsed nodes has the
  39.149 -  name ``\<^verbatim>\<open>[....]\<close>''. To uncollapse the nodes again, simply
  39.150 -  click on the red arrow or on the node with the name ``\<^verbatim>\<open>[....]\<close>''.
  39.151 -  Similar to the directory browser, the contents of
  39.152 -  theory files can be displayed by double clicking on the
  39.153 -  corresponding node.
  39.154 +  When pointing on an ordinary node, an upward and a downward arrow is shown.
  39.155 +  Initially, both of these arrows are green. Clicking on the upward or
  39.156 +  downward arrow collapses all predecessor or successor nodes, respectively.
  39.157 +  The arrow's color then changes to red, indicating that the predecessor or
  39.158 +  successor nodes are currently collapsed. The node corresponding to the
  39.159 +  collapsed nodes has the name ``\<^verbatim>\<open>[....]\<close>''. To uncollapse the nodes again,
  39.160 +  simply click on the red arrow or on the node with the name ``\<^verbatim>\<open>[....]\<close>''.
  39.161 +  Similar to the directory browser, the contents of theory files can be
  39.162 +  displayed by double clicking on the corresponding node.
  39.163  \<close>
  39.164  
  39.165  
  39.166  subsubsection \<open>The ``File'' menu\<close>
  39.167  
  39.168  text \<open>
  39.169 -  Due to Java Applet security restrictions this menu is only available
  39.170 -  in the full application version. The meaning of the menu items is as
  39.171 -  follows:
  39.172 +  Due to Java Applet security restrictions this menu is only available in the
  39.173 +  full application version. The meaning of the menu items is as follows:
  39.174  
  39.175    \<^descr>[Open \dots] Open a new graph file.
  39.176  
  39.177 -  \<^descr>[Export to PostScript] Outputs the current graph in Postscript
  39.178 -  format, appropriately scaled to fit on one single sheet of A4 paper.
  39.179 -  The resulting file can be printed directly.
  39.180 +  \<^descr>[Export to PostScript] Outputs the current graph in Postscript format,
  39.181 +  appropriately scaled to fit on one single sheet of A4 paper. The resulting
  39.182 +  file can be printed directly.
  39.183  
  39.184 -  \<^descr>[Export to EPS] Outputs the current graph in Encapsulated
  39.185 -  Postscript format. The resulting file can be included in other
  39.186 -  documents.
  39.187 +  \<^descr>[Export to EPS] Outputs the current graph in Encapsulated Postscript
  39.188 +  format. The resulting file can be included in other documents.
  39.189  
  39.190    \<^descr>[Quit] Quit the graph browser.
  39.191  \<close>
  39.192 @@ -150,22 +144,20 @@
  39.193  
  39.194    \<^descr>[\<open>vertex_name\<close>] The name of the vertex.
  39.195  
  39.196 -  \<^descr>[\<open>vertex_ID\<close>] The vertex identifier. Note that there may
  39.197 -  be several vertices with equal names, whereas identifiers must be
  39.198 -  unique.
  39.199 +  \<^descr>[\<open>vertex_ID\<close>] The vertex identifier. Note that there may be several
  39.200 +  vertices with equal names, whereas identifiers must be unique.
  39.201  
  39.202 -  \<^descr>[\<open>dir_name\<close>] The name of the ``directory'' the vertex
  39.203 -  should be placed in.  A ``\<^verbatim>\<open>+\<close>'' sign after \<open>dir_name\<close> indicates that the nodes in the directory are initially
  39.204 -  visible. Directories are initially invisible by default.
  39.205 +  \<^descr>[\<open>dir_name\<close>] The name of the ``directory'' the vertex should be placed in.
  39.206 +  A ``\<^verbatim>\<open>+\<close>'' sign after \<open>dir_name\<close> indicates that the nodes in the directory
  39.207 +  are initially visible. Directories are initially invisible by default.
  39.208  
  39.209 -  \<^descr>[\<open>path\<close>] The path of the corresponding theory file. This
  39.210 -  is specified relatively to the path of the graph definition file.
  39.211 +  \<^descr>[\<open>path\<close>] The path of the corresponding theory file. This is specified
  39.212 +  relatively to the path of the graph definition file.
  39.213  
  39.214 -  \<^descr>[List of successor/predecessor nodes] A ``\<^verbatim>\<open><\<close>''
  39.215 -  sign before the list means that successor nodes are listed, a
  39.216 -  ``\<^verbatim>\<open>>\<close>'' sign means that predecessor nodes are listed. If
  39.217 -  neither ``\<^verbatim>\<open><\<close>'' nor ``\<^verbatim>\<open>>\<close>'' is found, the
  39.218 -  browser assumes that successor nodes are listed.
  39.219 +  \<^descr>[List of successor/predecessor nodes] A ``\<^verbatim>\<open><\<close>'' sign before the list means
  39.220 +  that successor nodes are listed, a ``\<^verbatim>\<open>>\<close>'' sign means that predecessor
  39.221 +  nodes are listed. If neither ``\<^verbatim>\<open><\<close>'' nor ``\<^verbatim>\<open>>\<close>'' is found, the browser
  39.222 +  assumes that successor nodes are listed.
  39.223  \<close>
  39.224  
  39.225  
  39.226 @@ -188,33 +180,28 @@
  39.227  
  39.228    ISABELLE_COMPONENT_REPOSITORY="http://isabelle.in.tum.de/components"\<close>}
  39.229  
  39.230 -  Components are initialized as described in \secref{sec:components}
  39.231 -  in a permissive manner, which can mark components as ``missing''.
  39.232 -  This state is amended by letting @{tool "components"} download and
  39.233 -  unpack components that are published on the default component
  39.234 -  repository @{url "http://isabelle.in.tum.de/components/"} in
  39.235 -  particular.
  39.236 +  Components are initialized as described in \secref{sec:components} in a
  39.237 +  permissive manner, which can mark components as ``missing''. This state is
  39.238 +  amended by letting @{tool "components"} download and unpack components that
  39.239 +  are published on the default component repository @{url
  39.240 +  "http://isabelle.in.tum.de/components/"} in particular.
  39.241  
  39.242 -  Option \<^verbatim>\<open>-R\<close> specifies an alternative component
  39.243 -  repository.  Note that \<^verbatim>\<open>file:///\<close> URLs can be used for
  39.244 -  local directories.
  39.245 +  Option \<^verbatim>\<open>-R\<close> specifies an alternative component repository. Note that
  39.246 +  \<^verbatim>\<open>file:///\<close> URLs can be used for local directories.
  39.247  
  39.248 -  Option \<^verbatim>\<open>-a\<close> selects all missing components to be
  39.249 -  resolved.  Explicit components may be named as command
  39.250 -  line-arguments as well.  Note that components are uniquely
  39.251 -  identified by their base name, while the installation takes place in
  39.252 -  the location that was specified in the attempt to initialize the
  39.253 -  component before.
  39.254 +  Option \<^verbatim>\<open>-a\<close> selects all missing components to be resolved. Explicit
  39.255 +  components may be named as command line-arguments as well. Note that
  39.256 +  components are uniquely identified by their base name, while the
  39.257 +  installation takes place in the location that was specified in the attempt
  39.258 +  to initialize the component before.
  39.259  
  39.260 -  Option \<^verbatim>\<open>-l\<close> lists the current state of available and
  39.261 -  missing components with their location (full name) within the
  39.262 -  file-system.
  39.263 +  Option \<^verbatim>\<open>-l\<close> lists the current state of available and missing components
  39.264 +  with their location (full name) within the file-system.
  39.265  
  39.266 -  Option \<^verbatim>\<open>-I\<close> initializes the user settings file to
  39.267 -  subscribe to the standard components specified in the Isabelle
  39.268 -  repository clone --- this does not make any sense for regular
  39.269 -  Isabelle releases.  If the file already exists, it needs to be
  39.270 -  edited manually according to the printed explanation.
  39.271 +  Option \<^verbatim>\<open>-I\<close> initializes the user settings file to subscribe to the standard
  39.272 +  components specified in the Isabelle repository clone --- this does not make
  39.273 +  any sense for regular Isabelle releases. If the file already exists, it
  39.274 +  needs to be edited manually according to the printed explanation.
  39.275  \<close>
  39.276  
  39.277  
  39.278 @@ -236,14 +223,14 @@
  39.279    Run Isabelle process with raw ML console and line editor
  39.280    (default ISABELLE_LINE_EDITOR).\<close>}
  39.281  
  39.282 -  The \<^verbatim>\<open>-l\<close> option specifies the logic session name. By default,
  39.283 -  its heap image is checked and built on demand, but the option \<^verbatim>\<open>-n\<close> skips that.
  39.284 +  The \<^verbatim>\<open>-l\<close> option specifies the logic session name. By default, its heap
  39.285 +  image is checked and built on demand, but the option \<^verbatim>\<open>-n\<close> skips that.
  39.286  
  39.287 -  Options \<^verbatim>\<open>-d\<close>, \<^verbatim>\<open>-o\<close>, \<^verbatim>\<open>-s\<close> are passed
  39.288 -  directly to @{tool build} (\secref{sec:tool-build}).
  39.289 +  Options \<^verbatim>\<open>-d\<close>, \<^verbatim>\<open>-o\<close>, \<^verbatim>\<open>-s\<close> are passed directly to @{tool build}
  39.290 +  (\secref{sec:tool-build}).
  39.291  
  39.292 -  Options \<^verbatim>\<open>-m\<close>, \<^verbatim>\<open>-o\<close> are passed directly to the
  39.293 -  underlying Isabelle process (\secref{sec:isabelle-process}).
  39.294 +  Options \<^verbatim>\<open>-m\<close>, \<^verbatim>\<open>-o\<close> are passed directly to the underlying Isabelle process
  39.295 +  (\secref{sec:isabelle-process}).
  39.296  
  39.297    The Isabelle process is run through the line editor that is specified via
  39.298    the settings variable @{setting ISABELLE_LINE_EDITOR} (e.g.\
  39.299 @@ -259,19 +246,18 @@
  39.300  
  39.301  section \<open>Displaying documents \label{sec:tool-display}\<close>
  39.302  
  39.303 -text \<open>The @{tool_def display} tool displays documents in DVI or PDF
  39.304 -  format:
  39.305 +text \<open>
  39.306 +  The @{tool_def display} tool displays documents in DVI or PDF format:
  39.307    @{verbatim [display]
  39.308  \<open>Usage: isabelle display DOCUMENT
  39.309  
  39.310    Display DOCUMENT (in DVI or PDF format).\<close>}
  39.311  
  39.312    \<^medskip>
  39.313 -  The settings @{setting DVI_VIEWER} and @{setting
  39.314 -  PDF_VIEWER} determine the programs for viewing the corresponding
  39.315 -  file formats.  Normally this opens the document via the desktop
  39.316 -  environment, potentially in an asynchronous manner with re-use of
  39.317 -  previews views.
  39.318 +  The settings @{setting DVI_VIEWER} and @{setting PDF_VIEWER} determine the
  39.319 +  programs for viewing the corresponding file formats. Normally this opens the
  39.320 +  document via the desktop environment, potentially in an asynchronous manner
  39.321 +  with re-use of previews views.
  39.322  \<close>
  39.323  
  39.324  
  39.325 @@ -284,27 +270,27 @@
  39.326  
  39.327    View Isabelle documentation.\<close>}
  39.328  
  39.329 -  If called without arguments, it lists all available documents. Each
  39.330 -  line starts with an identifier, followed by a short description. Any
  39.331 -  of these identifiers may be specified as arguments, in order to
  39.332 -  display the corresponding document (see also
  39.333 -  \secref{sec:tool-display}).
  39.334 +  If called without arguments, it lists all available documents. Each line
  39.335 +  starts with an identifier, followed by a short description. Any of these
  39.336 +  identifiers may be specified as arguments, in order to display the
  39.337 +  corresponding document (see also \secref{sec:tool-display}).
  39.338  
  39.339    \<^medskip>
  39.340 -  The @{setting ISABELLE_DOCS} setting specifies the list of
  39.341 -  directories (separated by colons) to be scanned for documentations.
  39.342 +  The @{setting ISABELLE_DOCS} setting specifies the list of directories
  39.343 +  (separated by colons) to be scanned for documentations.
  39.344  \<close>
  39.345  
  39.346  
  39.347  section \<open>Shell commands within the settings environment \label{sec:tool-env}\<close>
  39.348  
  39.349 -text \<open>The @{tool_def env} tool is a direct wrapper for the standard
  39.350 -  \<^verbatim>\<open>/usr/bin/env\<close> command on POSIX systems, running within
  39.351 -  the Isabelle settings environment (\secref{sec:settings}).
  39.352 +text \<open>
  39.353 +  The @{tool_def env} tool is a direct wrapper for the standard
  39.354 +  \<^verbatim>\<open>/usr/bin/env\<close> command on POSIX systems, running within the Isabelle
  39.355 +  settings environment (\secref{sec:settings}).
  39.356  
  39.357 -  The command-line arguments are that of the underlying version of
  39.358 -  \<^verbatim>\<open>env\<close>.  For example, the following invokes an instance of
  39.359 -  the GNU Bash shell within the Isabelle environment:
  39.360 +  The command-line arguments are that of the underlying version of \<^verbatim>\<open>env\<close>. For
  39.361 +  example, the following invokes an instance of the GNU Bash shell within the
  39.362 +  Isabelle environment:
  39.363    @{verbatim [display] \<open>isabelle env bash\<close>}
  39.364  \<close>
  39.365  
  39.366 @@ -325,38 +311,39 @@
  39.367  
  39.368    Get value of VARNAMES from the Isabelle settings.\<close>}
  39.369  
  39.370 -  With the \<^verbatim>\<open>-a\<close> option, one may inspect the full process
  39.371 -  environment that Isabelle related programs are run in. This usually
  39.372 -  contains much more variables than are actually Isabelle settings.
  39.373 -  Normally, output is a list of lines of the form \<open>name\<close>\<^verbatim>\<open>=\<close>\<open>value\<close>. The \<^verbatim>\<open>-b\<close> option
  39.374 -  causes only the values to be printed.
  39.375 +  With the \<^verbatim>\<open>-a\<close> option, one may inspect the full process environment that
  39.376 +  Isabelle related programs are run in. This usually contains much more
  39.377 +  variables than are actually Isabelle settings. Normally, output is a list of
  39.378 +  lines of the form \<open>name\<close>\<^verbatim>\<open>=\<close>\<open>value\<close>. The \<^verbatim>\<open>-b\<close> option causes only the values
  39.379 +  to be printed.
  39.380  
  39.381 -  Option \<^verbatim>\<open>-d\<close> produces a dump of the complete environment
  39.382 -  to the specified file.  Entries are terminated by the ASCII null
  39.383 -  character, i.e.\ the C string terminator.
  39.384 +  Option \<^verbatim>\<open>-d\<close> produces a dump of the complete environment to the specified
  39.385 +  file. Entries are terminated by the ASCII null character, i.e.\ the C string
  39.386 +  terminator.
  39.387  \<close>
  39.388  
  39.389  
  39.390  subsubsection \<open>Examples\<close>
  39.391  
  39.392 -text \<open>Get the location of @{setting ISABELLE_HOME_USER} where
  39.393 -  user-specific information is stored:
  39.394 +text \<open>
  39.395 +  Get the location of @{setting ISABELLE_HOME_USER} where user-specific
  39.396 +  information is stored:
  39.397    @{verbatim [display] \<open>isabelle getenv ISABELLE_HOME_USER\<close>}
  39.398  
  39.399    \<^medskip>
  39.400 -  Get the value only of the same settings variable, which is
  39.401 -  particularly useful in shell scripts:
  39.402 +  Get the value only of the same settings variable, which is particularly
  39.403 +  useful in shell scripts:
  39.404    @{verbatim [display] \<open>isabelle getenv -b ISABELLE_OUTPUT\<close>}
  39.405  \<close>
  39.406  
  39.407  
  39.408  section \<open>Installing standalone Isabelle executables \label{sec:tool-install}\<close>
  39.409  
  39.410 -text \<open>By default, the main Isabelle binaries (@{executable
  39.411 -  "isabelle"} etc.)  are just run from their location within the
  39.412 -  distribution directory, probably indirectly by the shell through its
  39.413 -  @{setting PATH}.  Other schemes of installation are supported by the
  39.414 -  @{tool_def install} tool:
  39.415 +text \<open>
  39.416 +  By default, the main Isabelle binaries (@{executable "isabelle"} etc.) are
  39.417 +  just run from their location within the distribution directory, probably
  39.418 +  indirectly by the shell through its @{setting PATH}. Other schemes of
  39.419 +  installation are supported by the @{tool_def install} tool:
  39.420    @{verbatim [display]
  39.421  \<open>Usage: isabelle install [OPTIONS] BINDIR
  39.422  
  39.423 @@ -367,24 +354,26 @@
  39.424    Install Isabelle executables with absolute references to the
  39.425    distribution directory.\<close>}
  39.426  
  39.427 -  The \<^verbatim>\<open>-d\<close> option overrides the current Isabelle
  39.428 -  distribution directory as determined by @{setting ISABELLE_HOME}.
  39.429 +  The \<^verbatim>\<open>-d\<close> option overrides the current Isabelle distribution directory as
  39.430 +  determined by @{setting ISABELLE_HOME}.
  39.431  
  39.432 -  The \<open>BINDIR\<close> argument tells where executable wrapper scripts
  39.433 -  for @{executable "isabelle_process"} and @{executable isabelle}
  39.434 -  should be placed, which is typically a directory in the shell's
  39.435 -  @{setting PATH}, such as \<^verbatim>\<open>$HOME/bin\<close>.
  39.436 +  The \<open>BINDIR\<close> argument tells where executable wrapper scripts for
  39.437 +  @{executable "isabelle_process"} and @{executable isabelle} should be
  39.438 +  placed, which is typically a directory in the shell's @{setting PATH}, such
  39.439 +  as \<^verbatim>\<open>$HOME/bin\<close>.
  39.440  
  39.441    \<^medskip>
  39.442 -  It is also possible to make symbolic links of the main
  39.443 -  Isabelle executables manually, but making separate copies outside
  39.444 -  the Isabelle distribution directory will not work!\<close>
  39.445 +  It is also possible to make symbolic links of the main Isabelle executables
  39.446 +  manually, but making separate copies outside the Isabelle distribution
  39.447 +  directory will not work!
  39.448 +\<close>
  39.449  
  39.450  
  39.451  section \<open>Creating instances of the Isabelle logo\<close>
  39.452  
  39.453 -text \<open>The @{tool_def logo} tool creates instances of the generic
  39.454 -  Isabelle logo as EPS and PDF, for inclusion in {\LaTeX} documents.
  39.455 +text \<open>
  39.456 +  The @{tool_def logo} tool creates instances of the generic Isabelle logo as
  39.457 +  EPS and PDF, for inclusion in {\LaTeX} documents.
  39.458    @{verbatim [display]
  39.459  \<open>Usage: isabelle logo [OPTIONS] XYZ
  39.460  
  39.461 @@ -394,16 +383,15 @@
  39.462      -n NAME      alternative output base name (default "isabelle_xyx")
  39.463      -q           quiet mode\<close>}
  39.464  
  39.465 -  Option \<^verbatim>\<open>-n\<close> specifies an alternative (base) name for the
  39.466 -  generated files.  The default is \<^verbatim>\<open>isabelle_\<close>\<open>xyz\<close>
  39.467 -  in lower-case.
  39.468 +  Option \<^verbatim>\<open>-n\<close> specifies an alternative (base) name for the generated files.
  39.469 +  The default is \<^verbatim>\<open>isabelle_\<close>\<open>xyz\<close> in lower-case.
  39.470  
  39.471    Option \<^verbatim>\<open>-q\<close> omits printing of the result file name.
  39.472  
  39.473    \<^medskip>
  39.474 -  Implementors of Isabelle tools and applications are
  39.475 -  encouraged to make derived Isabelle logos for their own projects
  39.476 -  using this template.\<close>
  39.477 +  Implementors of Isabelle tools and applications are encouraged to make
  39.478 +  derived Isabelle logos for their own projects using this template.
  39.479 +\<close>
  39.480  
  39.481  
  39.482  section \<open>Output the version identifier of the Isabelle distribution\<close>
  39.483 @@ -419,53 +407,49 @@
  39.484    Display Isabelle version information.\<close>}
  39.485  
  39.486    \<^medskip>
  39.487 -  The default is to output the full version string of the
  39.488 -  Isabelle distribution, e.g.\ ``\<^verbatim>\<open>Isabelle2012: May 2012\<close>.
  39.489 +  The default is to output the full version string of the Isabelle
  39.490 +  distribution, e.g.\ ``\<^verbatim>\<open>Isabelle2012: May 2012\<close>.
  39.491  
  39.492 -  The \<^verbatim>\<open>-i\<close> option produces a short identification derived
  39.493 -  from the Mercurial id of the @{setting ISABELLE_HOME} directory.
  39.494 +  The \<^verbatim>\<open>-i\<close> option produces a short identification derived from the Mercurial
  39.495 +  id of the @{setting ISABELLE_HOME} directory.
  39.496  \<close>
  39.497  
  39.498  
  39.499  section \<open>Convert XML to YXML\<close>
  39.500  
  39.501  text \<open>
  39.502 -  The @{tool_def yxml} tool converts a standard XML document (stdin)
  39.503 -  to the much simpler and more efficient YXML format of Isabelle
  39.504 -  (stdout).  The YXML format is defined as follows.
  39.505 -
  39.506 -  \<^enum> The encoding is always UTF-8.
  39.507 +  The @{tool_def yxml} tool converts a standard XML document (stdin) to the
  39.508 +  much simpler and more efficient YXML format of Isabelle (stdout). The YXML
  39.509 +  format is defined as follows.
  39.510  
  39.511 -  \<^enum> Body text is represented verbatim (no escaping, no special
  39.512 -  treatment of white space, no named entities, no CDATA chunks, no
  39.513 -  comments).
  39.514 +    \<^enum> The encoding is always UTF-8.
  39.515  
  39.516 -  \<^enum> Markup elements are represented via ASCII control characters
  39.517 -  \<open>\<^bold>X = 5\<close> and \<open>\<^bold>Y = 6\<close> as follows:
  39.518 +    \<^enum> Body text is represented verbatim (no escaping, no special treatment of
  39.519 +    white space, no named entities, no CDATA chunks, no comments).
  39.520  
  39.521 -  \begin{tabular}{ll}
  39.522 -    XML & YXML \\\hline
  39.523 -    \<^verbatim>\<open><\<close>\<open>name attribute\<close>\<^verbatim>\<open>=\<close>\<open>value \<dots>\<close>\<^verbatim>\<open>>\<close> &
  39.524 -    \<open>\<^bold>X\<^bold>Yname\<^bold>Yattribute\<close>\<^verbatim>\<open>=\<close>\<open>value\<dots>\<^bold>X\<close> \\
  39.525 -    \<^verbatim>\<open></\<close>\<open>name\<close>\<^verbatim>\<open>>\<close> & \<open>\<^bold>X\<^bold>Y\<^bold>X\<close> \\
  39.526 -  \end{tabular}
  39.527 +    \<^enum> Markup elements are represented via ASCII control characters \<open>\<^bold>X = 5\<close>
  39.528 +    and \<open>\<^bold>Y = 6\<close> as follows:
  39.529  
  39.530 -  There is no special case for empty body text, i.e.\ \<^verbatim>\<open><foo/>\<close>
  39.531 -  is treated like \<^verbatim>\<open><foo></foo>\<close>.  Also note that
  39.532 -  \<open>\<^bold>X\<close> and \<open>\<^bold>Y\<close> may never occur in
  39.533 -  well-formed XML documents.
  39.534 +    \begin{tabular}{ll}
  39.535 +      XML & YXML \\\hline
  39.536 +      \<^verbatim>\<open><\<close>\<open>name attribute\<close>\<^verbatim>\<open>=\<close>\<open>value \<dots>\<close>\<^verbatim>\<open>>\<close> &
  39.537 +      \<open>\<^bold>X\<^bold>Yname\<^bold>Yattribute\<close>\<^verbatim>\<open>=\<close>\<open>value\<dots>\<^bold>X\<close> \\
  39.538 +      \<^verbatim>\<open></\<close>\<open>name\<close>\<^verbatim>\<open>>\<close> & \<open>\<^bold>X\<^bold>Y\<^bold>X\<close> \\
  39.539 +    \end{tabular}
  39.540  
  39.541 +    There is no special case for empty body text, i.e.\ \<^verbatim>\<open><foo/>\<close> is treated
  39.542 +    like \<^verbatim>\<open><foo></foo>\<close>. Also note that \<open>\<^bold>X\<close> and \<open>\<^bold>Y\<close> may never occur in
  39.543 +    well-formed XML documents.
  39.544  
  39.545    Parsing YXML is pretty straight-forward: split the text into chunks
  39.546 -  separated by \<open>\<^bold>X\<close>, then split each chunk into
  39.547 -  sub-chunks separated by \<open>\<^bold>Y\<close>.  Markup chunks start
  39.548 -  with an empty sub-chunk, and a second empty sub-chunk indicates
  39.549 -  close of an element.  Any other non-empty chunk consists of plain
  39.550 -  text.  For example, see @{file "~~/src/Pure/PIDE/yxml.ML"} or
  39.551 -  @{file "~~/src/Pure/PIDE/yxml.scala"}.
  39.552 +  separated by \<open>\<^bold>X\<close>, then split each chunk into sub-chunks separated by \<open>\<^bold>Y\<close>.
  39.553 +  Markup chunks start with an empty sub-chunk, and a second empty sub-chunk
  39.554 +  indicates close of an element. Any other non-empty chunk consists of plain
  39.555 +  text. For example, see @{file "~~/src/Pure/PIDE/yxml.ML"} or @{file
  39.556 +  "~~/src/Pure/PIDE/yxml.scala"}.
  39.557  
  39.558 -  YXML documents may be detected quickly by checking that the first
  39.559 -  two characters are \<open>\<^bold>X\<^bold>Y\<close>.
  39.560 +  YXML documents may be detected quickly by checking that the first two
  39.561 +  characters are \<open>\<^bold>X\<^bold>Y\<close>.
  39.562  \<close>
  39.563  
  39.564  end
  39.565 \ No newline at end of file
    40.1 --- a/src/Doc/System/Presentation.thy	Tue Nov 10 14:18:41 2015 +0000
    40.2 +++ b/src/Doc/System/Presentation.thy	Tue Nov 10 14:43:29 2015 +0000
    40.3 @@ -1,24 +1,27 @@
    40.4 +(*:wrap=hard:maxLineLen=78:*)
    40.5 +
    40.6  theory Presentation
    40.7  imports Base
    40.8  begin
    40.9  
   40.10  chapter \<open>Presenting theories \label{ch:present}\<close>
   40.11  
   40.12 -text \<open>Isabelle provides several ways to present the outcome of
   40.13 -  formal developments, including WWW-based browsable libraries or
   40.14 -  actual printable documents.  Presentation is centered around the
   40.15 -  concept of \<^emph>\<open>sessions\<close> (\chref{ch:session}).  The global session
   40.16 -  structure is that of a tree, with Isabelle Pure at its root, further
   40.17 -  object-logics derived (e.g.\ HOLCF from HOL, and HOL from Pure), and
   40.18 -  application sessions further on in the hierarchy.
   40.19 +text \<open>
   40.20 +  Isabelle provides several ways to present the outcome of formal
   40.21 +  developments, including WWW-based browsable libraries or actual printable
   40.22 +  documents. Presentation is centered around the concept of \<^emph>\<open>sessions\<close>
   40.23 +  (\chref{ch:session}). The global session structure is that of a tree, with
   40.24 +  Isabelle Pure at its root, further object-logics derived (e.g.\ HOLCF from
   40.25 +  HOL, and HOL from Pure), and application sessions further on in the
   40.26 +  hierarchy.
   40.27  
   40.28 -  The tools @{tool_ref mkroot} and @{tool_ref build} provide the
   40.29 -  primary means for managing Isabelle sessions, including proper setup
   40.30 -  for presentation; @{tool build} takes care to have @{executable_ref
   40.31 -  "isabelle_process"} run any additional stages required for document
   40.32 -  preparation, notably the @{tool_ref document} and @{tool_ref latex}.
   40.33 -  The complete tool chain for managing batch-mode Isabelle sessions is
   40.34 -  illustrated in \figref{fig:session-tools}.
   40.35 +  The tools @{tool_ref mkroot} and @{tool_ref build} provide the primary means
   40.36 +  for managing Isabelle sessions, including proper setup for presentation;
   40.37 +  @{tool build} takes care to have @{executable_ref "isabelle_process"} run
   40.38 +  any additional stages required for document preparation, notably the
   40.39 +  @{tool_ref document} and @{tool_ref latex}. The complete tool chain for
   40.40 +  managing batch-mode Isabelle sessions is illustrated in
   40.41 +  \figref{fig:session-tools}.
   40.42  
   40.43    \begin{figure}[htbp]
   40.44    \begin{center}
   40.45 @@ -53,58 +56,55 @@
   40.46  text \<open>
   40.47    \index{theory browsing information|bold}
   40.48  
   40.49 -  As a side-effect of building sessions, Isabelle is able to generate
   40.50 -  theory browsing information, including HTML documents that show the
   40.51 -  theory sources and the relationship with its ancestors and
   40.52 -  descendants.  Besides the HTML file that is generated for every
   40.53 -  theory, Isabelle stores links to all theories of a session in an
   40.54 -  index file.  As a second hierarchy, groups of sessions are organized
   40.55 -  as \<^emph>\<open>chapters\<close>, with a separate index.  Note that the implicit
   40.56 -  tree structure of the session build hierarchy is \<^emph>\<open>not\<close> relevant
   40.57 +  As a side-effect of building sessions, Isabelle is able to generate theory
   40.58 +  browsing information, including HTML documents that show the theory sources
   40.59 +  and the relationship with its ancestors and descendants. Besides the HTML
   40.60 +  file that is generated for every theory, Isabelle stores links to all
   40.61 +  theories of a session in an index file. As a second hierarchy, groups of
   40.62 +  sessions are organized as \<^emph>\<open>chapters\<close>, with a separate index. Note that the
   40.63 +  implicit tree structure of the session build hierarchy is \<^emph>\<open>not\<close> relevant
   40.64    for the presentation.
   40.65  
   40.66 -  Isabelle also generates graph files that represent the theory
   40.67 -  dependencies within a session.  There is a graph browser Java applet
   40.68 -  embedded in the generated HTML pages, and also a stand-alone
   40.69 -  application that allows browsing theory graphs without having to
   40.70 -  start a WWW client first.  The latter version also includes features
   40.71 -  such as generating Postscript files, which are not available in the
   40.72 -  applet version.  See \secref{sec:browse} for further information.
   40.73 +  Isabelle also generates graph files that represent the theory dependencies
   40.74 +  within a session. There is a graph browser Java applet embedded in the
   40.75 +  generated HTML pages, and also a stand-alone application that allows
   40.76 +  browsing theory graphs without having to start a WWW client first. The
   40.77 +  latter version also includes features such as generating Postscript files,
   40.78 +  which are not available in the applet version. See \secref{sec:browse} for
   40.79 +  further information.
   40.80  
   40.81    \<^medskip>
   40.82 -  The easiest way to let Isabelle generate theory browsing information
   40.83 -  for existing sessions is to invoke @{tool build} with suitable
   40.84 -  options:
   40.85 +  The easiest way to let Isabelle generate theory browsing information for
   40.86 +  existing sessions is to invoke @{tool build} with suitable options:
   40.87    @{verbatim [display] \<open>isabelle build -o browser_info -v -c FOL\<close>}
   40.88  
   40.89 -  The presentation output will appear in \<^verbatim>\<open>$ISABELLE_BROWSER_INFO/FOL/FOL\<close>
   40.90 -  as reported by the above verbose invocation of the build process.
   40.91 +  The presentation output will appear in \<^verbatim>\<open>$ISABELLE_BROWSER_INFO/FOL/FOL\<close> as
   40.92 +  reported by the above verbose invocation of the build process.
   40.93  
   40.94    Many Isabelle sessions (such as \<^verbatim>\<open>HOL-Library\<close> in @{file
   40.95 -  "~~/src/HOL/Library"}) also provide actual printable documents.
   40.96 -  These are prepared automatically as well if enabled like this:
   40.97 +  "~~/src/HOL/Library"}) also provide actual printable documents. These are
   40.98 +  prepared automatically as well if enabled like this:
   40.99    @{verbatim [display] \<open>isabelle build -o browser_info -o document=pdf -v -c HOL-Library\<close>}
  40.100  
  40.101 -  Enabling both browser info and document preparation simultaneously
  40.102 -  causes an appropriate ``document'' link to be included in the HTML
  40.103 -  index.  Documents may be generated independently of browser
  40.104 -  information as well, see \secref{sec:tool-document} for further
  40.105 -  details.
  40.106 +  Enabling both browser info and document preparation simultaneously causes an
  40.107 +  appropriate ``document'' link to be included in the HTML index. Documents
  40.108 +  may be generated independently of browser information as well, see
  40.109 +  \secref{sec:tool-document} for further details.
  40.110  
  40.111    \<^bigskip>
  40.112 -  The theory browsing information is stored in a
  40.113 -  sub-directory directory determined by the @{setting_ref
  40.114 -  ISABELLE_BROWSER_INFO} setting plus a prefix corresponding to the
  40.115 -  session chapter and identifier.  In order to present Isabelle
  40.116 -  applications on the web, the corresponding subdirectory from
  40.117 -  @{setting ISABELLE_BROWSER_INFO} can be put on a WWW server.\<close>
  40.118 +  The theory browsing information is stored in a sub-directory directory
  40.119 +  determined by the @{setting_ref ISABELLE_BROWSER_INFO} setting plus a prefix
  40.120 +  corresponding to the session chapter and identifier. In order to present
  40.121 +  Isabelle applications on the web, the corresponding subdirectory from
  40.122 +  @{setting ISABELLE_BROWSER_INFO} can be put on a WWW server.
  40.123 +\<close>
  40.124  
  40.125  
  40.126  section \<open>Preparing session root directories \label{sec:tool-mkroot}\<close>
  40.127  
  40.128 -text \<open>The @{tool_def mkroot} tool configures a given directory as
  40.129 -  session root, with some \<^verbatim>\<open>ROOT\<close> file and optional document
  40.130 -  source directory.  Its usage is:
  40.131 +text \<open>
  40.132 +  The @{tool_def mkroot} tool configures a given directory as session root,
  40.133 +  with some \<^verbatim>\<open>ROOT\<close> file and optional document source directory. Its usage is:
  40.134    @{verbatim [display]
  40.135  \<open>Usage: isabelle mkroot [OPTIONS] [DIR]
  40.136  
  40.137 @@ -114,46 +114,45 @@
  40.138  
  40.139    Prepare session root DIR (default: current directory).\<close>}
  40.140  
  40.141 -  The results are placed in the given directory \<open>dir\<close>, which
  40.142 -  refers to the current directory by default.  The @{tool mkroot} tool
  40.143 -  is conservative in the sense that it does not overwrite existing
  40.144 -  files or directories.  Earlier attempts to generate a session root
  40.145 -  need to be deleted manually.
  40.146 +  The results are placed in the given directory \<open>dir\<close>, which refers to the
  40.147 +  current directory by default. The @{tool mkroot} tool is conservative in the
  40.148 +  sense that it does not overwrite existing files or directories. Earlier
  40.149 +  attempts to generate a session root need to be deleted manually.
  40.150  
  40.151    \<^medskip>
  40.152 -  Option \<^verbatim>\<open>-d\<close> indicates that the session shall be
  40.153 -  accompanied by a formal document, with \<open>DIR\<close>\<^verbatim>\<open>/document/root.tex\<close>
  40.154 -  as its {\LaTeX} entry point (see also \chref{ch:present}).
  40.155 +  Option \<^verbatim>\<open>-d\<close> indicates that the session shall be accompanied by a formal
  40.156 +  document, with \<open>DIR\<close>\<^verbatim>\<open>/document/root.tex\<close> as its {\LaTeX} entry point (see
  40.157 +  also \chref{ch:present}).
  40.158  
  40.159 -  Option \<^verbatim>\<open>-n\<close> allows to specify an alternative session
  40.160 -  name; otherwise the base name of the given directory is used.
  40.161 +  Option \<^verbatim>\<open>-n\<close> allows to specify an alternative session name; otherwise the
  40.162 +  base name of the given directory is used.
  40.163  
  40.164    \<^medskip>
  40.165 -  The implicit Isabelle settings variable @{setting
  40.166 -  ISABELLE_LOGIC} specifies the parent session, and @{setting
  40.167 -  ISABELLE_DOCUMENT_FORMAT} the document format to be filled filled
  40.168 -  into the generated \<^verbatim>\<open>ROOT\<close> file.
  40.169 +  The implicit Isabelle settings variable @{setting ISABELLE_LOGIC} specifies
  40.170 +  the parent session, and @{setting ISABELLE_DOCUMENT_FORMAT} the document
  40.171 +  format to be filled filled into the generated \<^verbatim>\<open>ROOT\<close> file.
  40.172  \<close>
  40.173  
  40.174  
  40.175  subsubsection \<open>Examples\<close>
  40.176  
  40.177 -text \<open>Produce session \<^verbatim>\<open>Test\<close> (with document preparation)
  40.178 -  within a separate directory of the same name:
  40.179 +text \<open>
  40.180 +  Produce session \<^verbatim>\<open>Test\<close> (with document preparation) within a separate
  40.181 +  directory of the same name:
  40.182    @{verbatim [display] \<open>isabelle mkroot -d Test && isabelle build -D Test\<close>}
  40.183  
  40.184    \<^medskip>
  40.185 -  Upgrade the current directory into a session ROOT with
  40.186 -  document preparation, and build it:
  40.187 +  Upgrade the current directory into a session ROOT with document preparation,
  40.188 +  and build it:
  40.189    @{verbatim [display] \<open>isabelle mkroot -d && isabelle build -D .\<close>}
  40.190  \<close>
  40.191  
  40.192  
  40.193  section \<open>Preparing Isabelle session documents \label{sec:tool-document}\<close>
  40.194  
  40.195 -text \<open>The @{tool_def document} tool prepares logic session
  40.196 -  documents, processing the sources as provided by the user and
  40.197 -  generated by Isabelle.  Its usage is:
  40.198 +text \<open>
  40.199 +  The @{tool_def document} tool prepares logic session documents, processing
  40.200 +  the sources as provided by the user and generated by Isabelle. Its usage is:
  40.201    @{verbatim [display]
  40.202  \<open>Usage: isabelle document [OPTIONS] [DIR]
  40.203  
  40.204 @@ -168,90 +167,83 @@
  40.205  
  40.206    This tool is usually run automatically as part of the Isabelle build
  40.207    process, provided document preparation has been enabled via suitable
  40.208 -  options.  It may be manually invoked on the generated browser
  40.209 -  information document output as well, e.g.\ in case of errors
  40.210 -  encountered in the batch run.
  40.211 +  options. It may be manually invoked on the generated browser information
  40.212 +  document output as well, e.g.\ in case of errors encountered in the batch
  40.213 +  run.
  40.214  
  40.215    \<^medskip>
  40.216 -  The \<^verbatim>\<open>-c\<close> option tells @{tool document} to
  40.217 -  dispose the document sources after successful operation!  This is
  40.218 -  the right thing to do for sources generated by an Isabelle process,
  40.219 -  but take care of your files in manual document preparation!
  40.220 +  The \<^verbatim>\<open>-c\<close> option tells @{tool document} to dispose the document sources
  40.221 +  after successful operation! This is the right thing to do for sources
  40.222 +  generated by an Isabelle process, but take care of your files in manual
  40.223 +  document preparation!
  40.224  
  40.225    \<^medskip>
  40.226 -  The \<^verbatim>\<open>-n\<close> and \<^verbatim>\<open>-o\<close> option specify
  40.227 -  the final output file name and format, the default is ``\<^verbatim>\<open>document.dvi\<close>''.
  40.228 -  Note that the result will appear in the parent of the target \<^verbatim>\<open>DIR\<close>.
  40.229 +  The \<^verbatim>\<open>-n\<close> and \<^verbatim>\<open>-o\<close> option specify the final output file name and format,
  40.230 +  the default is ``\<^verbatim>\<open>document.dvi\<close>''. Note that the result will appear in the
  40.231 +  parent of the target \<^verbatim>\<open>DIR\<close>.
  40.232  
  40.233    \<^medskip>
  40.234 -  The \<^verbatim>\<open>-t\<close> option tells {\LaTeX} how to interpret
  40.235 -  tagged Isabelle command regions.  Tags are specified as a comma
  40.236 -  separated list of modifier/name pairs: ``\<^verbatim>\<open>+\<close>\<open>foo\<close>'' (or just ``\<open>foo\<close>'')
  40.237 -  means to keep, ``\<^verbatim>\<open>-\<close>\<open>foo\<close>'' to drop, and ``\<^verbatim>\<open>/\<close>\<open>foo\<close>'' to
  40.238 -  fold text tagged as \<open>foo\<close>.  The builtin default is equivalent
  40.239 -  to the tag specification ``\<^verbatim>\<open>+theory,+proof,+ML,+visible,-invisible\<close>'';
  40.240 -  see also the {\LaTeX} macros \<^verbatim>\<open>\isakeeptag\<close>, \<^verbatim>\<open>\isadroptag\<close>, and
  40.241 -  \<^verbatim>\<open>\isafoldtag\<close>, in @{file "~~/lib/texinputs/isabelle.sty"}.
  40.242 +  The \<^verbatim>\<open>-t\<close> option tells {\LaTeX} how to interpret tagged Isabelle command
  40.243 +  regions. Tags are specified as a comma separated list of modifier/name
  40.244 +  pairs: ``\<^verbatim>\<open>+\<close>\<open>foo\<close>'' (or just ``\<open>foo\<close>'') means to keep, ``\<^verbatim>\<open>-\<close>\<open>foo\<close>'' to
  40.245 +  drop, and ``\<^verbatim>\<open>/\<close>\<open>foo\<close>'' to fold text tagged as \<open>foo\<close>. The builtin default is
  40.246 +  equivalent to the tag specification
  40.247 +  ``\<^verbatim>\<open>+theory,+proof,+ML,+visible,-invisible\<close>''; see also the {\LaTeX} macros
  40.248 +  \<^verbatim>\<open>\isakeeptag\<close>, \<^verbatim>\<open>\isadroptag\<close>, and \<^verbatim>\<open>\isafoldtag\<close>, in @{file
  40.249 +  "~~/lib/texinputs/isabelle.sty"}.
  40.250  
  40.251    \<^medskip>
  40.252 -  Document preparation requires a \<^verbatim>\<open>document\<close>
  40.253 -  directory within the session sources.  This directory is supposed to
  40.254 -  contain all the files needed to produce the final document --- apart
  40.255 -  from the actual theories which are generated by Isabelle.
  40.256 +  Document preparation requires a \<^verbatim>\<open>document\<close> directory within the session
  40.257 +  sources. This directory is supposed to contain all the files needed to
  40.258 +  produce the final document --- apart from the actual theories which are
  40.259 +  generated by Isabelle.
  40.260  
  40.261    \<^medskip>
  40.262 -  For most practical purposes, @{tool document} is smart
  40.263 -  enough to create any of the specified output formats, taking
  40.264 -  \<^verbatim>\<open>root.tex\<close> supplied by the user as a starting point.  This
  40.265 -  even includes multiple runs of {\LaTeX} to accommodate references
  40.266 -  and bibliographies (the latter assumes \<^verbatim>\<open>root.bib\<close> within
  40.267 -  the same directory).
  40.268 +  For most practical purposes, @{tool document} is smart enough to create any
  40.269 +  of the specified output formats, taking \<^verbatim>\<open>root.tex\<close> supplied by the user as
  40.270 +  a starting point. This even includes multiple runs of {\LaTeX} to
  40.271 +  accommodate references and bibliographies (the latter assumes \<^verbatim>\<open>root.bib\<close>
  40.272 +  within the same directory).
  40.273  
  40.274 -  In more complex situations, a separate \<^verbatim>\<open>build\<close> script for
  40.275 -  the document sources may be given.  It is invoked with command-line
  40.276 -  arguments for the document format and the document variant name.
  40.277 -  The script needs to produce corresponding output files, e.g.\
  40.278 -  \<^verbatim>\<open>root.pdf\<close> for target format \<^verbatim>\<open>pdf\<close> (and default
  40.279 -  variants).  The main work can be again delegated to @{tool latex},
  40.280 -  but it is also possible to harvest generated {\LaTeX} sources and
  40.281 -  copy them elsewhere.
  40.282 +  In more complex situations, a separate \<^verbatim>\<open>build\<close> script for the document
  40.283 +  sources may be given. It is invoked with command-line arguments for the
  40.284 +  document format and the document variant name. The script needs to produce
  40.285 +  corresponding output files, e.g.\ \<^verbatim>\<open>root.pdf\<close> for target format \<^verbatim>\<open>pdf\<close> (and
  40.286 +  default variants). The main work can be again delegated to @{tool latex},
  40.287 +  but it is also possible to harvest generated {\LaTeX} sources and copy them
  40.288 +  elsewhere.
  40.289  
  40.290    \<^medskip>
  40.291 -  When running the session, Isabelle copies the content of
  40.292 -  the original \<^verbatim>\<open>document\<close> directory into its proper place
  40.293 -  within @{setting ISABELLE_BROWSER_INFO}, according to the session
  40.294 -  path and document variant.  Then, for any processed theory \<open>A\<close>
  40.295 -  some {\LaTeX} source is generated and put there as \<open>A\<close>\<^verbatim>\<open>.tex\<close>.
  40.296 -  Furthermore, a list of all generated theory
  40.297 -  files is put into \<^verbatim>\<open>session.tex\<close>.  Typically, the root
  40.298 -  {\LaTeX} file provided by the user would include \<^verbatim>\<open>session.tex\<close>
  40.299 -  to get a document containing all the theories.
  40.300 +  When running the session, Isabelle copies the content of the original
  40.301 +  \<^verbatim>\<open>document\<close> directory into its proper place within @{setting
  40.302 +  ISABELLE_BROWSER_INFO}, according to the session path and document variant.
  40.303 +  Then, for any processed theory \<open>A\<close> some {\LaTeX} source is generated and put
  40.304 +  there as \<open>A\<close>\<^verbatim>\<open>.tex\<close>. Furthermore, a list of all generated theory files is
  40.305 +  put into \<^verbatim>\<open>session.tex\<close>. Typically, the root {\LaTeX} file provided by the
  40.306 +  user would include \<^verbatim>\<open>session.tex\<close> to get a document containing all the
  40.307 +  theories.
  40.308  
  40.309 -  The {\LaTeX} versions of the theories require some macros defined in
  40.310 -  @{file "~~/lib/texinputs/isabelle.sty"}.  Doing \<^verbatim>\<open>\usepackage{isabelle}\<close>
  40.311 -  in \<^verbatim>\<open>root.tex\<close> should be fine; the underlying @{tool latex} already
  40.312 -  includes an appropriate path specification for {\TeX} inputs.
  40.313 +  The {\LaTeX} versions of the theories require some macros defined in @{file
  40.314 +  "~~/lib/texinputs/isabelle.sty"}. Doing \<^verbatim>\<open>\usepackage{isabelle}\<close> in
  40.315 +  \<^verbatim>\<open>root.tex\<close> should be fine; the underlying @{tool latex} already includes an
  40.316 +  appropriate path specification for {\TeX} inputs.
  40.317  
  40.318 -  If the text contains any references to Isabelle symbols (such as
  40.319 -  \<^verbatim>\<open>\<forall>\<close>) then \<^verbatim>\<open>isabellesym.sty\<close> should be included as well.
  40.320 -  This package contains a standard set of {\LaTeX} macro definitions
  40.321 -  \<^verbatim>\<open>\isasym\<close>\<open>foo\<close> corresponding to \<^verbatim>\<open>\\<close>\<^verbatim>\<open><\<close>\<open>foo\<close>\<^verbatim>\<open>>\<close>,
  40.322 -  see @{cite "isabelle-implementation"} for a
  40.323 -  complete list of predefined Isabelle symbols.  Users may invent
  40.324 -  further symbols as well, just by providing {\LaTeX} macros in a
  40.325 -  similar fashion as in @{file "~~/lib/texinputs/isabellesym.sty"} of
  40.326 -  the Isabelle distribution.
  40.327 +  If the text contains any references to Isabelle symbols (such as \<^verbatim>\<open>\<forall>\<close>) then
  40.328 +  \<^verbatim>\<open>isabellesym.sty\<close> should be included as well. This package contains a
  40.329 +  standard set of {\LaTeX} macro definitions \<^verbatim>\<open>\isasym\<close>\<open>foo\<close> corresponding to
  40.330 +  \<^verbatim>\<open>\\<close>\<^verbatim>\<open><\<close>\<open>foo\<close>\<^verbatim>\<open>>\<close>, see @{cite "isabelle-implementation"} for a complete list
  40.331 +  of predefined Isabelle symbols. Users may invent further symbols as well,
  40.332 +  just by providing {\LaTeX} macros in a similar fashion as in @{file
  40.333 +  "~~/lib/texinputs/isabellesym.sty"} of the Isabelle distribution.
  40.334  
  40.335 -  For proper setup of DVI and PDF documents (with hyperlinks and
  40.336 -  bookmarks), we recommend to include @{file
  40.337 -  "~~/lib/texinputs/pdfsetup.sty"} as well.
  40.338 +  For proper setup of DVI and PDF documents (with hyperlinks and bookmarks),
  40.339 +  we recommend to include @{file "~~/lib/texinputs/pdfsetup.sty"} as well.
  40.340  
  40.341    \<^medskip>
  40.342 -  As a final step of Isabelle document preparation, @{tool
  40.343 -  document}~\<^verbatim>\<open>-c\<close> is run on the resulting copy of the
  40.344 -  \<^verbatim>\<open>document\<close> directory.  Thus the actual output document is
  40.345 -  built and installed in its proper place.  The generated sources are
  40.346 -  deleted after successful run of {\LaTeX} and friends.
  40.347 +  As a final step of Isabelle document preparation, @{tool document}~\<^verbatim>\<open>-c\<close> is
  40.348 +  run on the resulting copy of the \<^verbatim>\<open>document\<close> directory. Thus the actual
  40.349 +  output document is built and installed in its proper place. The generated
  40.350 +  sources are deleted after successful run of {\LaTeX} and friends.
  40.351  
  40.352    Some care is needed if the document output location is configured
  40.353    differently, say within a directory whose content is still required
  40.354 @@ -262,8 +254,9 @@
  40.355  section \<open>Running {\LaTeX} within the Isabelle environment
  40.356    \label{sec:tool-latex}\<close>
  40.357  
  40.358 -text \<open>The @{tool_def latex} tool provides the basic interface for
  40.359 -  Isabelle document preparation.  Its usage is:
  40.360 +text \<open>
  40.361 +  The @{tool_def latex} tool provides the basic interface for Isabelle
  40.362 +  document preparation. Its usage is:
  40.363    @{verbatim [display]
  40.364  \<open>Usage: isabelle latex [OPTIONS] [FILE]
  40.365  
  40.366 @@ -274,32 +267,30 @@
  40.367    Run LaTeX (and related tools) on FILE (default root.tex),
  40.368    producing the specified output format.\<close>}
  40.369  
  40.370 -  Appropriate {\LaTeX}-related programs are run on the input file,
  40.371 -  according to the given output format: @{executable latex},
  40.372 -  @{executable pdflatex}, @{executable dvips}, @{executable bibtex}
  40.373 -  (for \<^verbatim>\<open>bbl\<close>), and @{executable makeindex} (for \<^verbatim>\<open>idx\<close>).
  40.374 -  The actual commands are determined from the settings
  40.375 -  environment (@{setting ISABELLE_PDFLATEX} etc.).
  40.376 +  Appropriate {\LaTeX}-related programs are run on the input file, according
  40.377 +  to the given output format: @{executable latex}, @{executable pdflatex},
  40.378 +  @{executable dvips}, @{executable bibtex} (for \<^verbatim>\<open>bbl\<close>), and @{executable
  40.379 +  makeindex} (for \<^verbatim>\<open>idx\<close>). The actual commands are determined from the
  40.380 +  settings environment (@{setting ISABELLE_PDFLATEX} etc.).
  40.381  
  40.382 -  The \<^verbatim>\<open>sty\<close> output format causes the Isabelle style files to
  40.383 -  be updated from the distribution.  This is useful in special
  40.384 -  situations where the document sources are to be processed another
  40.385 -  time by separate tools.
  40.386 +  The \<^verbatim>\<open>sty\<close> output format causes the Isabelle style files to be updated from
  40.387 +  the distribution. This is useful in special situations where the document
  40.388 +  sources are to be processed another time by separate tools.
  40.389  
  40.390 -  The \<^verbatim>\<open>syms\<close> output is for internal use; it generates lists
  40.391 -  of symbols that are available without loading additional {\LaTeX}
  40.392 -  packages.
  40.393 +  The \<^verbatim>\<open>syms\<close> output is for internal use; it generates lists of symbols that
  40.394 +  are available without loading additional {\LaTeX} packages.
  40.395  \<close>
  40.396  
  40.397  
  40.398  subsubsection \<open>Examples\<close>
  40.399  
  40.400 -text \<open>Invoking @{tool latex} by hand may be occasionally useful when
  40.401 -  debugging failed attempts of the automatic document preparation
  40.402 -  stage of batch-mode Isabelle.  The abortive process leaves the
  40.403 -  sources at a certain place within @{setting ISABELLE_BROWSER_INFO},
  40.404 -  see the runtime error message for details.  This enables users to
  40.405 -  inspect {\LaTeX} runs in further detail, e.g.\ like this:
  40.406 +text \<open>
  40.407 +  Invoking @{tool latex} by hand may be occasionally useful when debugging
  40.408 +  failed attempts of the automatic document preparation stage of batch-mode
  40.409 +  Isabelle. The abortive process leaves the sources at a certain place within
  40.410 +  @{setting ISABELLE_BROWSER_INFO}, see the runtime error message for details.
  40.411 +  This enables users to inspect {\LaTeX} runs in further detail, e.g.\ like
  40.412 +  this:
  40.413  
  40.414    @{verbatim [display]
  40.415  \<open>cd "$(isabelle getenv -b ISABELLE_BROWSER_INFO)/Unsorted/Test/document"
    41.1 --- a/src/Doc/System/Scala.thy	Tue Nov 10 14:18:41 2015 +0000
    41.2 +++ b/src/Doc/System/Scala.thy	Tue Nov 10 14:43:29 2015 +0000
    41.3 @@ -1,43 +1,47 @@
    41.4 +(*:wrap=hard:maxLineLen=78:*)
    41.5 +
    41.6  theory Scala
    41.7  imports Base
    41.8  begin
    41.9  
   41.10  chapter \<open>Isabelle/Scala development tools\<close>
   41.11  
   41.12 -text \<open>Isabelle/ML and Isabelle/Scala are the two main language
   41.13 -environments for Isabelle tool implementations.  There are some basic
   41.14 -command-line tools to work with the underlying Java Virtual Machine,
   41.15 -the Scala toplevel and compiler.  Note that Isabelle/jEdit
   41.16 -@{cite "isabelle-jedit"} provides a Scala Console for interactive
   41.17 -experimentation within the running application.\<close>
   41.18 +text \<open>
   41.19 +  Isabelle/ML and Isabelle/Scala are the two main language environments for
   41.20 +  Isabelle tool implementations. There are some basic command-line tools to
   41.21 +  work with the underlying Java Virtual Machine, the Scala toplevel and
   41.22 +  compiler. Note that Isabelle/jEdit @{cite "isabelle-jedit"} provides a Scala
   41.23 +  Console for interactive experimentation within the running application.
   41.24 +\<close>
   41.25  
   41.26  
   41.27  section \<open>Java Runtime Environment within Isabelle \label{sec:tool-java}\<close>
   41.28  
   41.29 -text \<open>The @{tool_def java} tool is a direct wrapper for the Java
   41.30 -  Runtime Environment, within the regular Isabelle settings
   41.31 -  environment (\secref{sec:settings}).  The command line arguments are
   41.32 -  that of the underlying Java version.  It is run in \<^verbatim>\<open>-server\<close> mode
   41.33 -  if possible, to improve performance (at the cost of extra startup time).
   41.34 +text \<open>
   41.35 +  The @{tool_def java} tool is a direct wrapper for the Java Runtime
   41.36 +  Environment, within the regular Isabelle settings environment
   41.37 +  (\secref{sec:settings}). The command line arguments are that of the
   41.38 +  underlying Java version. It is run in \<^verbatim>\<open>-server\<close> mode if possible, to
   41.39 +  improve performance (at the cost of extra startup time).
   41.40  
   41.41 -  The \<^verbatim>\<open>java\<close> executable is the one within @{setting
   41.42 -  ISABELLE_JDK_HOME}, according to the standard directory layout for
   41.43 -  official JDK distributions.  The class loader is augmented such that
   41.44 -  the name space of \<^verbatim>\<open>Isabelle/Pure.jar\<close> is available,
   41.45 -  which is the main Isabelle/Scala module.
   41.46 +  The \<^verbatim>\<open>java\<close> executable is the one within @{setting ISABELLE_JDK_HOME},
   41.47 +  according to the standard directory layout for official JDK distributions.
   41.48 +  The class loader is augmented such that the name space of
   41.49 +  \<^verbatim>\<open>Isabelle/Pure.jar\<close> is available, which is the main Isabelle/Scala module.
   41.50  
   41.51 -  For example, the following command-line invokes the main method of
   41.52 -  class \<^verbatim>\<open>isabelle.GUI_Setup\<close>, which opens a windows with
   41.53 -  some diagnostic information about the Isabelle environment:
   41.54 +  For example, the following command-line invokes the main method of class
   41.55 +  \<^verbatim>\<open>isabelle.GUI_Setup\<close>, which opens a windows with some diagnostic
   41.56 +  information about the Isabelle environment:
   41.57    @{verbatim [display] \<open>isabelle java isabelle.GUI_Setup\<close>}
   41.58  \<close>
   41.59  
   41.60  
   41.61  section \<open>Scala toplevel \label{sec:tool-scala}\<close>
   41.62  
   41.63 -text \<open>The @{tool_def scala} tool is a direct wrapper for the Scala
   41.64 -  toplevel; see also @{tool java} above.  The command line arguments
   41.65 -  are that of the underlying Scala version.
   41.66 +text \<open>
   41.67 +  The @{tool_def scala} tool is a direct wrapper for the Scala toplevel; see
   41.68 +  also @{tool java} above. The command line arguments are that of the
   41.69 +  underlying Scala version.
   41.70  
   41.71    This allows to interact with Isabelle/Scala in TTY mode like this:
   41.72    @{verbatim [display]
   41.73 @@ -51,32 +55,33 @@
   41.74  
   41.75  section \<open>Scala compiler \label{sec:tool-scalac}\<close>
   41.76  
   41.77 -text \<open>The @{tool_def scalac} tool is a direct wrapper for the Scala
   41.78 -  compiler; see also @{tool scala} above.  The command line arguments
   41.79 -  are that of the underlying Scala version.
   41.80 +text \<open>
   41.81 +  The @{tool_def scalac} tool is a direct wrapper for the Scala compiler; see
   41.82 +  also @{tool scala} above. The command line arguments are that of the
   41.83 +  underlying Scala version.
   41.84  
   41.85    This allows to compile further Scala modules, depending on existing
   41.86 -  Isabelle/Scala functionality.  The resulting class or jar files can
   41.87 -  be added to the Java classpath using the \<^verbatim>\<open>classpath\<close> Bash
   41.88 -  function that is provided by the Isabelle process environment.  Thus
   41.89 -  add-on components can register themselves in a modular manner, see
   41.90 -  also \secref{sec:components}.
   41.91 +  Isabelle/Scala functionality. The resulting class or jar files can be added
   41.92 +  to the Java classpath using the \<^verbatim>\<open>classpath\<close> Bash function that is provided
   41.93 +  by the Isabelle process environment. Thus add-on components can register
   41.94 +  themselves in a modular manner, see also \secref{sec:components}.
   41.95  
   41.96 -  Note that jEdit @{cite "isabelle-jedit"} has its own mechanisms for
   41.97 -  adding plugin components, which needs special attention since
   41.98 -  it overrides the standard Java class loader.\<close>
   41.99 +  Note that jEdit @{cite "isabelle-jedit"} has its own mechanisms for adding
  41.100 +  plugin components, which needs special attention since it overrides the
  41.101 +  standard Java class loader.
  41.102 +\<close>
  41.103  
  41.104  
  41.105  section \<open>Scala script wrapper\<close>
  41.106  
  41.107 -text \<open>The executable @{executable
  41.108 -  "$ISABELLE_HOME/bin/isabelle_scala_script"} allows to run
  41.109 -  Isabelle/Scala source files stand-alone programs, by using a
  41.110 +text \<open>
  41.111 +  The executable @{executable "$ISABELLE_HOME/bin/isabelle_scala_script"}
  41.112 +  allows to run Isabelle/Scala source files stand-alone programs, by using a
  41.113    suitable ``hash-bang'' line and executable file permissions.
  41.114  
  41.115 -  The subsequent example assumes that the main Isabelle binaries have
  41.116 -  been installed in some directory that is included in @{setting PATH}
  41.117 -  (see also @{tool "install"}):
  41.118 +  The subsequent example assumes that the main Isabelle binaries have been
  41.119 +  installed in some directory that is included in @{setting PATH} (see also
  41.120 +  @{tool "install"}):
  41.121    @{verbatim [display]
  41.122  \<open>#!/usr/bin/env isabelle_scala_script
  41.123  
  41.124 @@ -84,8 +89,8 @@
  41.125  Console.println("browser_info = " + options.bool("browser_info"))
  41.126  Console.println("document = " + options.string("document"))\<close>}
  41.127  
  41.128 -  Alternatively the full @{file
  41.129 -  "$ISABELLE_HOME/bin/isabelle_scala_script"} may be specified in
  41.130 -  expanded form.\<close>
  41.131 +  Alternatively the full @{file "$ISABELLE_HOME/bin/isabelle_scala_script"}
  41.132 +  may be specified in expanded form.
  41.133 +\<close>
  41.134  
  41.135  end
    42.1 --- a/src/Doc/System/Sessions.thy	Tue Nov 10 14:18:41 2015 +0000
    42.2 +++ b/src/Doc/System/Sessions.thy	Tue Nov 10 14:43:29 2015 +0000
    42.3 @@ -1,52 +1,52 @@
    42.4 +(*:wrap=hard:maxLineLen=78:*)
    42.5 +
    42.6  theory Sessions
    42.7  imports Base
    42.8  begin
    42.9  
   42.10  chapter \<open>Isabelle sessions and build management \label{ch:session}\<close>
   42.11  
   42.12 -text \<open>An Isabelle \<^emph>\<open>session\<close> consists of a collection of related
   42.13 -  theories that may be associated with formal documents
   42.14 -  (\chref{ch:present}).  There is also a notion of \<^emph>\<open>persistent
   42.15 -  heap\<close> image to capture the state of a session, similar to
   42.16 -  object-code in compiled programming languages.  Thus the concept of
   42.17 -  session resembles that of a ``project'' in common IDE environments,
   42.18 -  but the specific name emphasizes the connection to interactive
   42.19 -  theorem proving: the session wraps-up the results of
   42.20 -  user-interaction with the prover in a persistent form.
   42.21 +text \<open>
   42.22 +  An Isabelle \<^emph>\<open>session\<close> consists of a collection of related theories that may
   42.23 +  be associated with formal documents (\chref{ch:present}). There is also a
   42.24 +  notion of \<^emph>\<open>persistent heap\<close> image to capture the state of a session,
   42.25 +  similar to object-code in compiled programming languages. Thus the concept
   42.26 +  of session resembles that of a ``project'' in common IDE environments, but
   42.27 +  the specific name emphasizes the connection to interactive theorem proving:
   42.28 +  the session wraps-up the results of user-interaction with the prover in a
   42.29 +  persistent form.
   42.30  
   42.31 -  Application sessions are built on a given parent session, which may
   42.32 -  be built recursively on other parents.  Following this path in the
   42.33 -  hierarchy eventually leads to some major object-logic session like
   42.34 -  \<open>HOL\<close>, which itself is based on \<open>Pure\<close> as the common
   42.35 -  root of all sessions.
   42.36 +  Application sessions are built on a given parent session, which may be built
   42.37 +  recursively on other parents. Following this path in the hierarchy
   42.38 +  eventually leads to some major object-logic session like \<open>HOL\<close>, which itself
   42.39 +  is based on \<open>Pure\<close> as the common root of all sessions.
   42.40  
   42.41 -  Processing sessions may take considerable time.  Isabelle build
   42.42 -  management helps to organize this efficiently.  This includes
   42.43 -  support for parallel build jobs, in addition to the multithreaded
   42.44 -  theory and proof checking that is already provided by the prover
   42.45 -  process itself.\<close>
   42.46 +  Processing sessions may take considerable time. Isabelle build management
   42.47 +  helps to organize this efficiently. This includes support for parallel build
   42.48 +  jobs, in addition to the multithreaded theory and proof checking that is
   42.49 +  already provided by the prover process itself.
   42.50 +\<close>
   42.51  
   42.52  
   42.53  section \<open>Session ROOT specifications \label{sec:session-root}\<close>
   42.54  
   42.55 -text \<open>Session specifications reside in files called \<^verbatim>\<open>ROOT\<close>
   42.56 -  within certain directories, such as the home locations of registered
   42.57 -  Isabelle components or additional project directories given by the
   42.58 -  user.
   42.59 +text \<open>
   42.60 +  Session specifications reside in files called \<^verbatim>\<open>ROOT\<close> within certain
   42.61 +  directories, such as the home locations of registered Isabelle components or
   42.62 +  additional project directories given by the user.
   42.63  
   42.64 -  The ROOT file format follows the lexical conventions of the
   42.65 -  \<^emph>\<open>outer syntax\<close> of Isabelle/Isar, see also
   42.66 -  @{cite "isabelle-isar-ref"}.  This defines common forms like
   42.67 -  identifiers, names, quoted strings, verbatim text, nested comments
   42.68 -  etc.  The grammar for @{syntax session_chapter} and @{syntax
   42.69 -  session_entry} is given as syntax diagram below; each ROOT file may
   42.70 -  contain multiple specifications like this.  Chapters help to
   42.71 -  organize browser info (\secref{sec:info}), but have no formal
   42.72 -  meaning.  The default chapter is ``\<open>Unsorted\<close>''.
   42.73 +  The ROOT file format follows the lexical conventions of the \<^emph>\<open>outer syntax\<close>
   42.74 +  of Isabelle/Isar, see also @{cite "isabelle-isar-ref"}. This defines common
   42.75 +  forms like identifiers, names, quoted strings, verbatim text, nested
   42.76 +  comments etc. The grammar for @{syntax session_chapter} and @{syntax
   42.77 +  session_entry} is given as syntax diagram below; each ROOT file may contain
   42.78 +  multiple specifications like this. Chapters help to organize browser info
   42.79 +  (\secref{sec:info}), but have no formal meaning. The default chapter is
   42.80 +  ``\<open>Unsorted\<close>''.
   42.81  
   42.82 -  Isabelle/jEdit @{cite "isabelle-jedit"} includes a simple editing
   42.83 -  mode \<^verbatim>\<open>isabelle-root\<close> for session ROOT files, which is
   42.84 -  enabled by default for any file of that name.
   42.85 +  Isabelle/jEdit @{cite "isabelle-jedit"} includes a simple editing mode
   42.86 +  \<^verbatim>\<open>isabelle-root\<close> for session ROOT files, which is enabled by default for any
   42.87 +  file of that name.
   42.88  
   42.89    @{rail \<open>
   42.90      @{syntax_def session_chapter}: @'chapter' @{syntax name}
   42.91 @@ -77,151 +77,143 @@
   42.92      document_files: @'document_files' ('(' dir ')')? (@{syntax name}+)
   42.93    \<close>}
   42.94  
   42.95 -  \<^descr> \isakeyword{session}~\<open>A = B + body\<close> defines a new
   42.96 -  session \<open>A\<close> based on parent session \<open>B\<close>, with its
   42.97 -  content given in \<open>body\<close> (theories and auxiliary source files).
   42.98 -  Note that a parent (like \<open>HOL\<close>) is mandatory in practical
   42.99 +  \<^descr> \isakeyword{session}~\<open>A = B + body\<close> defines a new session \<open>A\<close> based on
  42.100 +  parent session \<open>B\<close>, with its content given in \<open>body\<close> (theories and auxiliary
  42.101 +  source files). Note that a parent (like \<open>HOL\<close>) is mandatory in practical
  42.102    applications: only Isabelle/Pure can bootstrap itself from nothing.
  42.103  
  42.104 -  All such session specifications together describe a hierarchy (tree)
  42.105 -  of sessions, with globally unique names.  The new session name
  42.106 -  \<open>A\<close> should be sufficiently long and descriptive to stand on
  42.107 -  its own in a potentially large library.
  42.108 +  All such session specifications together describe a hierarchy (tree) of
  42.109 +  sessions, with globally unique names. The new session name \<open>A\<close> should be
  42.110 +  sufficiently long and descriptive to stand on its own in a potentially large
  42.111 +  library.
  42.112  
  42.113 -  \<^descr> \isakeyword{session}~\<open>A (groups)\<close> indicates a
  42.114 -  collection of groups where the new session is a member.  Group names
  42.115 -  are uninterpreted and merely follow certain conventions.  For
  42.116 -  example, the Isabelle distribution tags some important sessions by
  42.117 -  the group name called ``\<open>main\<close>''.  Other projects may invent
  42.118 -  their own conventions, but this requires some care to avoid clashes
  42.119 +  \<^descr> \isakeyword{session}~\<open>A (groups)\<close> indicates a collection of groups where
  42.120 +  the new session is a member. Group names are uninterpreted and merely follow
  42.121 +  certain conventions. For example, the Isabelle distribution tags some
  42.122 +  important sessions by the group name called ``\<open>main\<close>''. Other projects may
  42.123 +  invent their own conventions, but this requires some care to avoid clashes
  42.124    within this unchecked name space.
  42.125  
  42.126 -  \<^descr> \isakeyword{session}~\<open>A\<close>~\isakeyword{in}~\<open>dir\<close>
  42.127 -  specifies an explicit directory for this session; by default this is
  42.128 -  the current directory of the \<^verbatim>\<open>ROOT\<close> file.
  42.129 +  \<^descr> \isakeyword{session}~\<open>A\<close>~\isakeyword{in}~\<open>dir\<close> specifies an explicit
  42.130 +  directory for this session; by default this is the current directory of the
  42.131 +  \<^verbatim>\<open>ROOT\<close> file.
  42.132  
  42.133 -  All theories and auxiliary source files are located relatively to
  42.134 -  the session directory.  The prover process is run within the same as
  42.135 -  its current working directory.
  42.136 -
  42.137 -  \<^descr> \isakeyword{description}~\<open>text\<close> is a free-form
  42.138 -  annotation for this session.
  42.139 +  All theories and auxiliary source files are located relatively to the
  42.140 +  session directory. The prover process is run within the same as its current
  42.141 +  working directory.
  42.142  
  42.143 -  \<^descr> \isakeyword{options}~\<open>[x = a, y = b, z]\<close> defines
  42.144 -  separate options (\secref{sec:system-options}) that are used when
  42.145 -  processing this session, but \<^emph>\<open>without\<close> propagation to child
  42.146 -  sessions.  Note that \<open>z\<close> abbreviates \<open>z = true\<close> for
  42.147 -  Boolean options.
  42.148 +  \<^descr> \isakeyword{description}~\<open>text\<close> is a free-form annotation for this
  42.149 +  session.
  42.150  
  42.151 -  \<^descr> \isakeyword{theories}~\<open>options names\<close> specifies a
  42.152 -  block of theories that are processed within an environment that is
  42.153 -  augmented by the given options, in addition to the global session
  42.154 -  options given before.  Any number of blocks of \isakeyword{theories}
  42.155 -  may be given.  Options are only active for each
  42.156 +  \<^descr> \isakeyword{options}~\<open>[x = a, y = b, z]\<close> defines separate options
  42.157 +  (\secref{sec:system-options}) that are used when processing this session,
  42.158 +  but \<^emph>\<open>without\<close> propagation to child sessions. Note that \<open>z\<close> abbreviates \<open>z =
  42.159 +  true\<close> for Boolean options.
  42.160 +
  42.161 +  \<^descr> \isakeyword{theories}~\<open>options names\<close> specifies a block of theories that
  42.162 +  are processed within an environment that is augmented by the given options,
  42.163 +  in addition to the global session options given before. Any number of blocks
  42.164 +  of \isakeyword{theories} may be given. Options are only active for each
  42.165    \isakeyword{theories} block separately.
  42.166  
  42.167 -  \<^descr> \isakeyword{files}~\<open>files\<close> lists additional source
  42.168 -  files that are involved in the processing of this session.  This
  42.169 -  should cover anything outside the formal content of the theory
  42.170 -  sources.  In contrast, files that are loaded formally
  42.171 -  within a theory, e.g.\ via @{command "ML_file"}, need not be
  42.172 +  \<^descr> \isakeyword{files}~\<open>files\<close> lists additional source files that are involved
  42.173 +  in the processing of this session. This should cover anything outside the
  42.174 +  formal content of the theory sources. In contrast, files that are loaded
  42.175 +  formally within a theory, e.g.\ via @{command "ML_file"}, need not be
  42.176    declared again.
  42.177  
  42.178 -  \<^descr> \isakeyword{document_files}~\<open>(\<close>\isakeyword{in}~\<open>base_dir) files\<close> lists source files for document preparation,
  42.179 -  typically \<^verbatim>\<open>.tex\<close> and \<^verbatim>\<open>.sty\<close> for {\LaTeX}.
  42.180 -  Only these explicitly given files are copied from the base directory
  42.181 -  to the document output directory, before formal document processing
  42.182 -  is started (see also \secref{sec:tool-document}).  The local path
  42.183 -  structure of the \<open>files\<close> is preserved, which allows to
  42.184 -  reconstruct the original directory hierarchy of \<open>base_dir\<close>.
  42.185 +  \<^descr> \isakeyword{document_files}~\<open>(\<close>\isakeyword{in}~\<open>base_dir) files\<close> lists
  42.186 +  source files for document preparation, typically \<^verbatim>\<open>.tex\<close> and \<^verbatim>\<open>.sty\<close> for
  42.187 +  {\LaTeX}. Only these explicitly given files are copied from the base
  42.188 +  directory to the document output directory, before formal document
  42.189 +  processing is started (see also \secref{sec:tool-document}). The local path
  42.190 +  structure of the \<open>files\<close> is preserved, which allows to reconstruct the
  42.191 +  original directory hierarchy of \<open>base_dir\<close>.
  42.192  
  42.193    \<^descr> \isakeyword{document_files}~\<open>files\<close> abbreviates
  42.194 -  \isakeyword{document_files}~\<open>(\<close>\isakeyword{in}~\<open>document) files\<close>, i.e.\ document sources are taken from the base
  42.195 -  directory \<^verbatim>\<open>document\<close> within the session root directory.
  42.196 +  \isakeyword{document_files}~\<open>(\<close>\isakeyword{in}~\<open>document) files\<close>, i.e.\
  42.197 +  document sources are taken from the base directory \<^verbatim>\<open>document\<close> within the
  42.198 +  session root directory.
  42.199  \<close>
  42.200  
  42.201  
  42.202  subsubsection \<open>Examples\<close>
  42.203  
  42.204 -text \<open>See @{file "~~/src/HOL/ROOT"} for a diversity of practically
  42.205 -  relevant situations, although it uses relatively complex
  42.206 -  quasi-hierarchic naming conventions like \<open>HOL\<dash>SPARK\<close>,
  42.207 -  \<open>HOL\<dash>SPARK\<dash>Examples\<close>.  An alternative is to use
  42.208 -  unqualified names that are relatively long and descriptive, as in
  42.209 -  the Archive of Formal Proofs (@{url "http://afp.sourceforge.net"}), for
  42.210 -  example.\<close>
  42.211 +text \<open>
  42.212 +  See @{file "~~/src/HOL/ROOT"} for a diversity of practically relevant
  42.213 +  situations, although it uses relatively complex quasi-hierarchic naming
  42.214 +  conventions like \<^verbatim>\<open>HOL-SPARK\<close>, \<^verbatim>\<open>HOL-SPARK-Examples\<close>. An alternative is to
  42.215 +  use unqualified names that are relatively long and descriptive, as in the
  42.216 +  Archive of Formal Proofs (@{url "http://afp.sourceforge.net"}), for
  42.217 +  example.
  42.218 +\<close>
  42.219  
  42.220  
  42.221  section \<open>System build options \label{sec:system-options}\<close>
  42.222  
  42.223 -text \<open>See @{file "~~/etc/options"} for the main defaults provided by
  42.224 -  the Isabelle distribution.  Isabelle/jEdit @{cite "isabelle-jedit"}
  42.225 -  includes a simple editing mode \<^verbatim>\<open>isabelle-options\<close> for
  42.226 -  this file-format.
  42.227 +text \<open>
  42.228 +  See @{file "~~/etc/options"} for the main defaults provided by the Isabelle
  42.229 +  distribution. Isabelle/jEdit @{cite "isabelle-jedit"} includes a simple
  42.230 +  editing mode \<^verbatim>\<open>isabelle-options\<close> for this file-format.
  42.231  
  42.232 -  The following options are particularly relevant to build Isabelle
  42.233 -  sessions, in particular with document preparation
  42.234 -  (\chref{ch:present}).
  42.235 +  The following options are particularly relevant to build Isabelle sessions,
  42.236 +  in particular with document preparation (\chref{ch:present}).
  42.237  
  42.238 -  \<^item> @{system_option_def "browser_info"} controls output of HTML
  42.239 -  browser info, see also \secref{sec:info}.
  42.240 +    \<^item> @{system_option_def "browser_info"} controls output of HTML browser
  42.241 +    info, see also \secref{sec:info}.
  42.242  
  42.243 -  \<^item> @{system_option_def "document"} specifies the document output
  42.244 -  format, see @{tool document} option \<^verbatim>\<open>-o\<close> in
  42.245 -  \secref{sec:tool-document}.  In practice, the most relevant values
  42.246 -  are \<^verbatim>\<open>document=false\<close> or \<^verbatim>\<open>document=pdf\<close>.
  42.247 +    \<^item> @{system_option_def "document"} specifies the document output format,
  42.248 +    see @{tool document} option \<^verbatim>\<open>-o\<close> in \secref{sec:tool-document}. In
  42.249 +    practice, the most relevant values are \<^verbatim>\<open>document=false\<close> or
  42.250 +    \<^verbatim>\<open>document=pdf\<close>.
  42.251  
  42.252 -  \<^item> @{system_option_def "document_output"} specifies an
  42.253 -  alternative directory for generated output of the document
  42.254 -  preparation system; the default is within the @{setting
  42.255 -  "ISABELLE_BROWSER_INFO"} hierarchy as explained in
  42.256 -  \secref{sec:info}.  See also @{tool mkroot}, which generates a
  42.257 -  default configuration with output readily available to the author of
  42.258 -  the document.
  42.259 +    \<^item> @{system_option_def "document_output"} specifies an alternative
  42.260 +    directory for generated output of the document preparation system; the
  42.261 +    default is within the @{setting "ISABELLE_BROWSER_INFO"} hierarchy as
  42.262 +    explained in \secref{sec:info}. See also @{tool mkroot}, which generates a
  42.263 +    default configuration with output readily available to the author of the
  42.264 +    document.
  42.265  
  42.266 -  \<^item> @{system_option_def "document_variants"} specifies document
  42.267 -  variants as a colon-separated list of \<open>name=tags\<close> entries,
  42.268 -  corresponding to @{tool document} options \<^verbatim>\<open>-n\<close> and
  42.269 -  \<^verbatim>\<open>-t\<close>.
  42.270 +    \<^item> @{system_option_def "document_variants"} specifies document variants as
  42.271 +    a colon-separated list of \<open>name=tags\<close> entries, corresponding to @{tool
  42.272 +    document} options \<^verbatim>\<open>-n\<close> and \<^verbatim>\<open>-t\<close>.
  42.273 +
  42.274 +    For example, \<^verbatim>\<open>document_variants=document:outline=/proof,/ML\<close> indicates
  42.275 +    two documents: the one called \<^verbatim>\<open>document\<close> with default tags, and the other
  42.276 +    called \<^verbatim>\<open>outline\<close> where proofs and ML sections are folded.
  42.277  
  42.278 -  For example, \<^verbatim>\<open>document_variants=document:outline=/proof,/ML\<close> indicates
  42.279 -  two documents: the one called \<^verbatim>\<open>document\<close> with default tags,
  42.280 -  and the other called \<^verbatim>\<open>outline\<close> where proofs and ML
  42.281 -  sections are folded.
  42.282 +    Document variant names are just a matter of conventions. It is also
  42.283 +    possible to use different document variant names (without tags) for
  42.284 +    different document root entries, see also \secref{sec:tool-document}.
  42.285  
  42.286 -  Document variant names are just a matter of conventions.  It is also
  42.287 -  possible to use different document variant names (without tags) for
  42.288 -  different document root entries, see also
  42.289 -  \secref{sec:tool-document}.
  42.290 +    \<^item> @{system_option_def "threads"} determines the number of worker threads
  42.291 +    for parallel checking of theories and proofs. The default \<open>0\<close> means that a
  42.292 +    sensible maximum value is determined by the underlying hardware. For
  42.293 +    machines with many cores or with hyperthreading, this is often requires
  42.294 +    manual adjustment (on the command-line or within personal settings or
  42.295 +    preferences, not within a session \<^verbatim>\<open>ROOT\<close>).
  42.296  
  42.297 -  \<^item> @{system_option_def "threads"} determines the number of worker
  42.298 -  threads for parallel checking of theories and proofs.  The default
  42.299 -  \<open>0\<close> means that a sensible maximum value is determined by the
  42.300 -  underlying hardware.  For machines with many cores or with
  42.301 -  hyperthreading, this is often requires manual adjustment (on the
  42.302 -  command-line or within personal settings or preferences, not within
  42.303 -  a session \<^verbatim>\<open>ROOT\<close>).
  42.304 +    \<^item> @{system_option_def "condition"} specifies a comma-separated list of
  42.305 +    process environment variables (or Isabelle settings) that are required for
  42.306 +    the subsequent theories to be processed. Conditions are considered
  42.307 +    ``true'' if the corresponding environment value is defined and non-empty.
  42.308  
  42.309 -  \<^item> @{system_option_def "condition"} specifies a comma-separated
  42.310 -  list of process environment variables (or Isabelle settings) that
  42.311 -  are required for the subsequent theories to be processed.
  42.312 -  Conditions are considered ``true'' if the corresponding environment
  42.313 -  value is defined and non-empty.
  42.314 +    For example, the \<^verbatim>\<open>condition=ISABELLE_FULL_TEST\<close> may be used to guard
  42.315 +    extraordinary theories, which are meant to be enabled explicitly via some
  42.316 +    shell prefix \<^verbatim>\<open>env ISABELLE_FULL_TEST=true\<close> before invoking @{tool build}.
  42.317  
  42.318 -  For example, the \<^verbatim>\<open>condition=ISABELLE_FULL_TEST\<close> may be
  42.319 -  used to guard extraordinary theories, which are meant to be enabled
  42.320 -  explicitly via some shell prefix \<^verbatim>\<open>env ISABELLE_FULL_TEST=true\<close>
  42.321 -  before invoking @{tool build}.
  42.322 +    \<^item> @{system_option_def "timeout"} and @{system_option_def "timeout_scale"}
  42.323 +    specify a real wall-clock timeout for the session as a whole: the two
  42.324 +    values are multiplied and taken as the number of seconds. Typically,
  42.325 +    @{system_option "timeout"} is given for individual sessions, and
  42.326 +    @{system_option "timeout_scale"} as global adjustment to overall hardware
  42.327 +    performance.
  42.328  
  42.329 -  \<^item> @{system_option_def "timeout"} specifies a real wall-clock
  42.330 -  timeout (in seconds) for the session as a whole.  The timer is
  42.331 -  controlled outside the ML process by the JVM that runs
  42.332 -  Isabelle/Scala.  Thus it is relatively reliable in canceling
  42.333 -  processes that get out of control, even if there is a deadlock
  42.334 -  without CPU time usage.
  42.335 +    The timer is controlled outside the ML process by the JVM that runs
  42.336 +    Isabelle/Scala. Thus it is relatively reliable in canceling processes that
  42.337 +    get out of control, even if there is a deadlock without CPU time usage.
  42.338  
  42.339 -
  42.340 -  The @{tool_def options} tool prints Isabelle system options.  Its
  42.341 +  The @{tool_def options} tool prints Isabelle system options. Its
  42.342    command-line usage is:
  42.343    @{verbatim [display]
  42.344  \<open>Usage: isabelle options [OPTIONS] [MORE_OPTIONS ...]
  42.345 @@ -235,32 +227,29 @@
  42.346    Report Isabelle system options, augmented by MORE_OPTIONS given as
  42.347    arguments NAME=VAL or NAME.\<close>}
  42.348  
  42.349 -  The command line arguments provide additional system options of the
  42.350 -  form \<open>name\<close>\<^verbatim>\<open>=\<close>\<open>value\<close> or \<open>name\<close>
  42.351 -  for Boolean options.
  42.352 +  The command line arguments provide additional system options of the form
  42.353 +  \<open>name\<close>\<^verbatim>\<open>=\<close>\<open>value\<close> or \<open>name\<close> for Boolean options.
  42.354 +
  42.355 +  Option \<^verbatim>\<open>-b\<close> augments the implicit environment of system options by the ones
  42.356 +  of @{setting ISABELLE_BUILD_OPTIONS}, cf.\ \secref{sec:tool-build}.
  42.357  
  42.358 -  Option \<^verbatim>\<open>-b\<close> augments the implicit environment of system
  42.359 -  options by the ones of @{setting ISABELLE_BUILD_OPTIONS}, cf.\
  42.360 -  \secref{sec:tool-build}.
  42.361 +  Option \<^verbatim>\<open>-g\<close> prints the value of the given option. Option \<^verbatim>\<open>-l\<close> lists all
  42.362 +  options with their declaration and current value.
  42.363  
  42.364 -  Option \<^verbatim>\<open>-g\<close> prints the value of the given option.
  42.365 -  Option \<^verbatim>\<open>-l\<close> lists all options with their declaration and
  42.366 -  current value.
  42.367 -
  42.368 -  Option \<^verbatim>\<open>-x\<close> specifies a file to export the result in
  42.369 -  YXML format, instead of printing it in human-readable form.
  42.370 +  Option \<^verbatim>\<open>-x\<close> specifies a file to export the result in YXML format, instead
  42.371 +  of printing it in human-readable form.
  42.372  \<close>
  42.373  
  42.374  
  42.375  section \<open>Invoking the build process \label{sec:tool-build}\<close>
  42.376  
  42.377 -text \<open>The @{tool_def build} tool invokes the build process for
  42.378 -  Isabelle sessions.  It manages dependencies between sessions,
  42.379 -  related sources of theories and auxiliary files, and target heap
  42.380 -  images.  Accordingly, it runs instances of the prover process with
  42.381 -  optional document preparation.  Its command-line usage
  42.382 -  is:\footnote{Isabelle/Scala provides the same functionality via
  42.383 -  \<^verbatim>\<open>isabelle.Build.build\<close>.}
  42.384 +text \<open>
  42.385 +  The @{tool_def build} tool invokes the build process for Isabelle sessions.
  42.386 +  It manages dependencies between sessions, related sources of theories and
  42.387 +  auxiliary files, and target heap images. Accordingly, it runs instances of
  42.388 +  the prover process with optional document preparation. Its command-line
  42.389 +  usage is:\<^footnote>\<open>Isabelle/Scala provides the same functionality via
  42.390 +  \<^verbatim>\<open>isabelle.Build.build\<close>.\<close>
  42.391    @{verbatim [display]
  42.392  \<open>Usage: isabelle build [OPTIONS] [SESSIONS ...]
  42.393  
  42.394 @@ -291,98 +280,87 @@
  42.395    ML_OPTIONS="..."\<close>}
  42.396  
  42.397    \<^medskip>
  42.398 -  Isabelle sessions are defined via session ROOT files as
  42.399 -  described in (\secref{sec:session-root}).  The totality of sessions
  42.400 -  is determined by collecting such specifications from all Isabelle
  42.401 -  component directories (\secref{sec:components}), augmented by more
  42.402 -  directories given via options \<^verbatim>\<open>-d\<close>~\<open>DIR\<close> on the
  42.403 -  command line.  Each such directory may contain a session
  42.404 +  Isabelle sessions are defined via session ROOT files as described in
  42.405 +  (\secref{sec:session-root}). The totality of sessions is determined by
  42.406 +  collecting such specifications from all Isabelle component directories
  42.407 +  (\secref{sec:components}), augmented by more directories given via options
  42.408 +  \<^verbatim>\<open>-d\<close>~\<open>DIR\<close> on the command line. Each such directory may contain a session
  42.409    \<^verbatim>\<open>ROOT\<close> file with several session specifications.
  42.410  
  42.411 -  Any session root directory may refer recursively to further
  42.412 -  directories of the same kind, by listing them in a catalog file
  42.413 -  \<^verbatim>\<open>ROOTS\<close> line-by-line.  This helps to organize large
  42.414 -  collections of session specifications, or to make \<^verbatim>\<open>-d\<close>
  42.415 -  command line options persistent (say within
  42.416 +  Any session root directory may refer recursively to further directories of
  42.417 +  the same kind, by listing them in a catalog file \<^verbatim>\<open>ROOTS\<close> line-by-line. This
  42.418 +  helps to organize large collections of session specifications, or to make
  42.419 +  \<^verbatim>\<open>-d\<close> command line options persistent (say within
  42.420    \<^verbatim>\<open>$ISABELLE_HOME_USER/ROOTS\<close>).
  42.421  
  42.422    \<^medskip>
  42.423 -  The subset of sessions to be managed is determined via
  42.424 -  individual \<open>SESSIONS\<close> given as command-line arguments, or
  42.425 -  session groups that are given via one or more options \<^verbatim>\<open>-g\<close>~\<open>NAME\<close>.
  42.426 -  Option \<^verbatim>\<open>-a\<close> selects all sessions.
  42.427 -  The build tool takes session dependencies into account: the set of
  42.428 -  selected sessions is completed by including all ancestors.
  42.429 +  The subset of sessions to be managed is determined via individual \<open>SESSIONS\<close>
  42.430 +  given as command-line arguments, or session groups that are given via one or
  42.431 +  more options \<^verbatim>\<open>-g\<close>~\<open>NAME\<close>. Option \<^verbatim>\<open>-a\<close> selects all sessions. The build tool
  42.432 +  takes session dependencies into account: the set of selected sessions is
  42.433 +  completed by including all ancestors.
  42.434  
  42.435    \<^medskip>
  42.436 -  One or more options \<^verbatim>\<open>-x\<close>~\<open>NAME\<close> specify
  42.437 -  sessions to be excluded. All descendents of excluded sessions are removed
  42.438 -  from the selection as specified above. Option \<^verbatim>\<open>-X\<close> is
  42.439 -  analogous to this, but excluded sessions are specified by session group
  42.440 -  membership.
  42.441 +  One or more options \<^verbatim>\<open>-x\<close>~\<open>NAME\<close> specify sessions to be excluded. All
  42.442 +  descendents of excluded sessions are removed from the selection as specified
  42.443 +  above. Option \<^verbatim>\<open>-X\<close> is analogous to this, but excluded sessions are
  42.444 +  specified by session group membership.
  42.445  
  42.446    \<^medskip>
  42.447 -  Option \<^verbatim>\<open>-R\<close> reverses the selection in the sense
  42.448 -  that it refers to its requirements: all ancestor sessions excluding
  42.449 -  the original selection.  This allows to prepare the stage for some
  42.450 -  build process with different options, before running the main build
  42.451 -  itself (without option \<^verbatim>\<open>-R\<close>).
  42.452 +  Option \<^verbatim>\<open>-R\<close> reverses the selection in the sense that it refers to its
  42.453 +  requirements: all ancestor sessions excluding the original selection. This
  42.454 +  allows to prepare the stage for some build process with different options,
  42.455 +  before running the main build itself (without option \<^verbatim>\<open>-R\<close>).
  42.456  
  42.457    \<^medskip>
  42.458 -  Option \<^verbatim>\<open>-D\<close> is similar to \<^verbatim>\<open>-d\<close>, but
  42.459 -  selects all sessions that are defined in the given directories.
  42.460 +  Option \<^verbatim>\<open>-D\<close> is similar to \<^verbatim>\<open>-d\<close>, but selects all sessions that are defined
  42.461 +  in the given directories.
  42.462  
  42.463    \<^medskip>
  42.464    The build process depends on additional options
  42.465 -  (\secref{sec:system-options}) that are passed to the prover
  42.466 -  eventually.  The settings variable @{setting_ref
  42.467 -  ISABELLE_BUILD_OPTIONS} allows to provide additional defaults, e.g.\
  42.468 -  \<^verbatim>\<open>ISABELLE_BUILD_OPTIONS="document=pdf threads=4"\<close>. Moreover,
  42.469 -  the environment of system build options may be augmented on the
  42.470 -  command line via \<^verbatim>\<open>-o\<close>~\<open>name\<close>\<^verbatim>\<open>=\<close>\<open>value\<close> or \<^verbatim>\<open>-o\<close>~\<open>name\<close>, which
  42.471 -  abbreviates \<^verbatim>\<open>-o\<close>~\<open>name\<close>\<^verbatim>\<open>=true\<close> for
  42.472 -  Boolean options.  Multiple occurrences of \<^verbatim>\<open>-o\<close> on the
  42.473 -  command-line are applied in the given order.
  42.474 +  (\secref{sec:system-options}) that are passed to the prover eventually. The
  42.475 +  settings variable @{setting_ref ISABELLE_BUILD_OPTIONS} allows to provide
  42.476 +  additional defaults, e.g.\ \<^verbatim>\<open>ISABELLE_BUILD_OPTIONS="document=pdf threads=4"\<close>.
  42.477 +  Moreover, the environment of system build options may be augmented on the
  42.478 +  command line via \<^verbatim>\<open>-o\<close>~\<open>name\<close>\<^verbatim>\<open>=\<close>\<open>value\<close> or \<^verbatim>\<open>-o\<close>~\<open>name\<close>, which abbreviates
  42.479 +  \<^verbatim>\<open>-o\<close>~\<open>name\<close>\<^verbatim>\<open>=true\<close> for Boolean options. Multiple occurrences of \<^verbatim>\<open>-o\<close> on
  42.480 +  the command-line are applied in the given order.
  42.481  
  42.482    \<^medskip>
  42.483 -  Option \<^verbatim>\<open>-b\<close> ensures that heap images are
  42.484 -  produced for all selected sessions.  By default, images are only
  42.485 -  saved for inner nodes of the hierarchy of sessions, as required for
  42.486 -  other sessions to continue later on.
  42.487 +  Option \<^verbatim>\<open>-b\<close> ensures that heap images are produced for all selected
  42.488 +  sessions. By default, images are only saved for inner nodes of the hierarchy
  42.489 +  of sessions, as required for other sessions to continue later on.
  42.490  
  42.491    \<^medskip>
  42.492 -  Option \<^verbatim>\<open>-c\<close> cleans all descendants of the
  42.493 -  selected sessions before performing the specified build operation.
  42.494 +  Option \<^verbatim>\<open>-c\<close> cleans all descendants of the selected sessions before
  42.495 +  performing the specified build operation.
  42.496  
  42.497    \<^medskip>
  42.498 -  Option \<^verbatim>\<open>-n\<close> omits the actual build process
  42.499 -  after the preparatory stage (including optional cleanup).  Note that
  42.500 -  the return code always indicates the status of the set of selected
  42.501 -  sessions.
  42.502 +  Option \<^verbatim>\<open>-n\<close> omits the actual build process after the preparatory stage
  42.503 +  (including optional cleanup). Note that the return code always indicates the
  42.504 +  status of the set of selected sessions.
  42.505  
  42.506    \<^medskip>
  42.507 -  Option \<^verbatim>\<open>-j\<close> specifies the maximum number of
  42.508 -  parallel build jobs (prover processes).  Each prover process is
  42.509 -  subject to a separate limit of parallel worker threads, cf.\ system
  42.510 -  option @{system_option_ref threads}.
  42.511 +  Option \<^verbatim>\<open>-j\<close> specifies the maximum number of parallel build jobs (prover
  42.512 +  processes). Each prover process is subject to a separate limit of parallel
  42.513 +  worker threads, cf.\ system option @{system_option_ref threads}.
  42.514  
  42.515    \<^medskip>
  42.516 -  Option \<^verbatim>\<open>-s\<close> enables \<^emph>\<open>system mode\<close>, which
  42.517 -  means that resulting heap images and log files are stored in
  42.518 -  @{file_unchecked "$ISABELLE_HOME/heaps"} instead of the default location
  42.519 -  @{setting ISABELLE_OUTPUT} (which is normally in @{setting
  42.520 -  ISABELLE_HOME_USER}, i.e.\ the user's home directory).
  42.521 +  Option \<^verbatim>\<open>-s\<close> enables \<^emph>\<open>system mode\<close>, which means that resulting heap images
  42.522 +  and log files are stored in @{file_unchecked "$ISABELLE_HOME/heaps"} instead
  42.523 +  of the default location @{setting ISABELLE_OUTPUT} (which is normally in
  42.524 +  @{setting ISABELLE_HOME_USER}, i.e.\ the user's home directory).
  42.525  
  42.526    \<^medskip>
  42.527 -  Option \<^verbatim>\<open>-v\<close> increases the general level of
  42.528 -  verbosity.  Option \<^verbatim>\<open>-l\<close> lists the source files that
  42.529 -  contribute to a session.
  42.530 +  Option \<^verbatim>\<open>-v\<close> increases the general level of verbosity. Option \<^verbatim>\<open>-l\<close> lists
  42.531 +  the source files that contribute to a session.
  42.532  
  42.533    \<^medskip>
  42.534 -  Option \<^verbatim>\<open>-k\<close> specifies a newly proposed keyword for
  42.535 -  outer syntax (multiple uses allowed). The theory sources are checked for
  42.536 -  conflicts wrt.\ this hypothetical change of syntax, e.g.\ to reveal
  42.537 -  occurrences of identifiers that need to be quoted.\<close>
  42.538 +  Option \<^verbatim>\<open>-k\<close> specifies a newly proposed keyword for outer syntax (multiple
  42.539 +  uses allowed). The theory sources are checked for conflicts wrt.\ this
  42.540 +  hypothetical change of syntax, e.g.\ to reveal occurrences of identifiers
  42.541 +  that need to be quoted.
  42.542 +\<close>
  42.543  
  42.544  
  42.545  subsubsection \<open>Examples\<close>
  42.546 @@ -396,23 +374,22 @@
  42.547    @{verbatim [display] \<open>isabelle build -b -g main\<close>}
  42.548  
  42.549    \<^smallskip>
  42.550 -  Provide a general overview of the status of all Isabelle
  42.551 -  sessions, without building anything:
  42.552 +  Provide a general overview of the status of all Isabelle sessions, without
  42.553 +  building anything:
  42.554    @{verbatim [display] \<open>isabelle build -a -n -v\<close>}
  42.555  
  42.556    \<^smallskip>
  42.557 -  Build all sessions with HTML browser info and PDF
  42.558 -  document preparation:
  42.559 +  Build all sessions with HTML browser info and PDF document preparation:
  42.560    @{verbatim [display] \<open>isabelle build -a -o browser_info -o document=pdf\<close>}
  42.561  
  42.562    \<^smallskip>
  42.563 -  Build all sessions with a maximum of 8 parallel prover
  42.564 -  processes and 4 worker threads each (on a machine with many cores):
  42.565 +  Build all sessions with a maximum of 8 parallel prover processes and 4
  42.566 +  worker threads each (on a machine with many cores):
  42.567    @{verbatim [display] \<open>isabelle build -a -j8 -o threads=4\<close>}
  42.568  
  42.569    \<^smallskip>
  42.570 -  Build some session images with cleanup of their
  42.571 -  descendants, while retaining their ancestry:
  42.572 +  Build some session images with cleanup of their descendants, while retaining
  42.573 +  their ancestry:
  42.574    @{verbatim [display] \<open>isabelle build -b -c HOL-Algebra HOL-Word\<close>}
  42.575  
  42.576    \<^smallskip>
  42.577 @@ -420,14 +397,14 @@
  42.578    @{verbatim [display] \<open>isabelle build -a -n -c\<close>}
  42.579  
  42.580    \<^smallskip>
  42.581 -  Build all sessions from some other directory hierarchy,
  42.582 -  according to the settings variable \<^verbatim>\<open>AFP\<close> that happens to
  42.583 -  be defined inside the Isabelle environment:
  42.584 +  Build all sessions from some other directory hierarchy, according to the
  42.585 +  settings variable \<^verbatim>\<open>AFP\<close> that happens to be defined inside the Isabelle
  42.586 +  environment:
  42.587    @{verbatim [display] \<open>isabelle build -D '$AFP'\<close>}
  42.588  
  42.589    \<^smallskip>
  42.590 -  Inform about the status of all sessions required for AFP,
  42.591 -  without building anything yet:
  42.592 +  Inform about the status of all sessions required for AFP, without building
  42.593 +  anything yet:
  42.594    @{verbatim [display] \<open>isabelle build -D '$AFP' -R -v -n\<close>}
  42.595  \<close>
  42.596  
    43.1 --- a/src/Doc/Tutorial/Documents/Documents.thy	Tue Nov 10 14:18:41 2015 +0000
    43.2 +++ b/src/Doc/Tutorial/Documents/Documents.thy	Tue Nov 10 14:43:29 2015 +0000
    43.3 @@ -112,7 +112,7 @@
    43.4    macros (see also \S\ref{sec:doc-prep-symbols}).  There are also a
    43.5    few predefined control symbols, such as \verb,\,\verb,<^sub>, and
    43.6    \verb,\,\verb,<^sup>, for sub- and superscript of the subsequent
    43.7 -  printable symbol, respectively.  For example, \verb,A\<^sup>\<star>, is
    43.8 +  printable symbol, respectively.  For example, \<^verbatim>\<open>A\<^sup>\<star>\<close>, is
    43.9    output as @{text "A\<^sup>\<star>"}.
   43.10  
   43.11    A number of symbols are considered letters by the Isabelle lexer and
   43.12 @@ -125,7 +125,7 @@
   43.13    in the trailing part of an identifier. This means that the input
   43.14  
   43.15    \medskip
   43.16 -  {\small\noindent \verb,\,\verb,<forall>\,\verb,<alpha>\<^sub>1.,~\verb,\,\verb,<alpha>\<^sub>1 = \,\verb,<Pi>\<^sub>\<A>,}
   43.17 +  {\small\noindent \<^verbatim>\<open>\<forall>\<alpha>\<^sub>1. \<alpha>\<^sub>1 = \<Pi>\<^sub>\<A>\<close>}
   43.18  
   43.19    \medskip
   43.20    \noindent is recognized as the term @{term "\<forall>\<alpha>\<^sub>1. \<alpha>\<^sub>1 = \<Pi>\<^sub>\<A>"} 
    44.1 --- a/src/FOL/ex/Locale_Test/Locale_Test1.thy	Tue Nov 10 14:18:41 2015 +0000
    44.2 +++ b/src/FOL/ex/Locale_Test/Locale_Test1.thy	Tue Nov 10 14:43:29 2015 +0000
    44.3 @@ -298,7 +298,7 @@
    44.4  
    44.5  section \<open>Interpretation between locales: sublocales\<close>
    44.6  
    44.7 -sublocale lgrp < right: rgrp
    44.8 +sublocale lgrp < right?: rgrp
    44.9  print_facts
   44.10  proof unfold_locales
   44.11    {
   44.12 @@ -504,7 +504,7 @@
   44.13  end
   44.14  
   44.15  interpretation x: logic_o "op \<and>" "Not"
   44.16 -  where bool_logic_o: "x.lor_o(x, y) \<longleftrightarrow> x \<or> y"
   44.17 +  rewrites bool_logic_o: "x.lor_o(x, y) \<longleftrightarrow> x \<or> y"
   44.18  proof -
   44.19    show bool_logic_o: "PROP logic_o(op \<and>, Not)" by unfold_locales fast+
   44.20    show "logic_o.lor_o(op \<and>, Not, x, y) \<longleftrightarrow> x \<or> y"
   44.21 @@ -546,7 +546,7 @@
   44.22  lemmas less_thm = less_def
   44.23  end
   44.24  
   44.25 -interpretation le: mixin gle where "reflexive.less(gle, x, y) \<longleftrightarrow> gless(x, y)"
   44.26 +interpretation le: mixin gle rewrites "reflexive.less(gle, x, y) \<longleftrightarrow> gless(x, y)"
   44.27  proof -
   44.28    show "mixin(gle)" by unfold_locales (rule grefl)
   44.29    note reflexive = this[unfolded mixin_def]
   44.30 @@ -588,7 +588,7 @@
   44.31  locale mixin4_mixin = mixin4_base
   44.32  
   44.33  interpretation le: mixin4_mixin gle
   44.34 -  where "reflexive.less(gle, x, y) \<longleftrightarrow> gless(x, y)"
   44.35 +  rewrites "reflexive.less(gle, x, y) \<longleftrightarrow> gless(x, y)"
   44.36  proof -
   44.37    show "mixin4_mixin(gle)" by unfold_locales (rule grefl)
   44.38    note reflexive = this[unfolded mixin4_mixin_def mixin4_base_def mixin_def]
   44.39 @@ -601,7 +601,7 @@
   44.40  lemmas less_thm4 = less_def
   44.41  end
   44.42  
   44.43 -locale mixin4_combined = le1: mixin4_mixin le' + le2: mixin4_copy le for le' le
   44.44 +locale mixin4_combined = le1?: mixin4_mixin le' + le2?: mixin4_copy le for le' le
   44.45  begin
   44.46  lemmas less_thm4' = less_def
   44.47  end
   44.48 @@ -620,7 +620,7 @@
   44.49  locale mixin5_inherited = mixin5_base
   44.50  
   44.51  interpretation le5: mixin5_base gle
   44.52 -  where "reflexive.less(gle, x, y) \<longleftrightarrow> gless(x, y)"
   44.53 +  rewrites "reflexive.less(gle, x, y) \<longleftrightarrow> gless(x, y)"
   44.54  proof -
   44.55    show "mixin5_base(gle)" by unfold_locales
   44.56    note reflexive = this[unfolded mixin5_base_def mixin_def]
   44.57 @@ -648,7 +648,7 @@
   44.58  interpretation le6: mixin6_inherited gle
   44.59    by unfold_locales
   44.60  interpretation le6: mixin6_base gle
   44.61 -  where "reflexive.less(gle, x, y) \<longleftrightarrow> gless(x, y)"
   44.62 +  rewrites "reflexive.less(gle, x, y) \<longleftrightarrow> gless(x, y)"
   44.63  proof -
   44.64    show "mixin6_base(gle)" by unfold_locales
   44.65    note reflexive = this[unfolded mixin6_base_def mixin_def]
   44.66 @@ -669,7 +669,7 @@
   44.67  locale mixin7_inherited = reflexive
   44.68  
   44.69  interpretation le7: mixin7_base gle
   44.70 -  where "reflexive.less(gle, x, y) \<longleftrightarrow> gless(x, y)"
   44.71 +  rewrites "reflexive.less(gle, x, y) \<longleftrightarrow> gless(x, y)"
   44.72  proof -
   44.73    show "mixin7_base(gle)" by unfold_locales
   44.74    note reflexive = this[unfolded mixin7_base_def mixin_def]
   44.75 @@ -726,8 +726,8 @@
   44.76  
   44.77  end
   44.78  
   44.79 -sublocale lgrp < "def": dgrp
   44.80 -  where one_equation: "dgrp.one(prod) = one" and inv_equation: "dgrp.inv(prod, x) = inv(x)"