1 (*:wrap=hard:maxLineLen=78:*)
7 chapter {* Introduction *}
9 section {* Concepts and terminology *}
13 parallel proof checking \cite{Wenzel:2009} \cite{Wenzel:2013:ITP}
15 asynchronous user interaction \cite{Wenzel:2010},
16 \cite{Wenzel:2012:UITP-EPTCS}
18 document-oriented proof processing and Prover IDE \cite{Wenzel:2011:CICM}
23 \item [PIDE] is a general framework for Prover IDEs based on the
24 Isabelle/Scala. It is built around a concept of \emph{asynchronous document
25 processing}, which is supported natively by the \emph{parallel proof engine}
26 that is implemented in Isabelle/ML.
28 \item [jEdit] is a sophisticated text editor \url{http://www.jedit.org}
29 implemented in Java. It is easily extensible by plugins written in any
30 language that works on the JVM, e.g.\ Scala.
32 \item [Isabelle/jEdit] is the main example application of the PIDE framework
33 and the default user-interface for Isabelle. It is targeted at beginners and
40 section {* The Isabelle/jEdit Prover IDE *}
43 \includegraphics[width=\textwidth]{isabelle-jedit}
45 Isabelle/jEdit consists of some plugins for the well-known jEdit text
46 editor \url{http://www.jedit.org}, according to the following
51 \item The original jEdit look-and-feel is generally preserved, although
52 some default properties have been changed to accommodate Isabelle (e.g.\
55 \item Formal Isabelle/Isar text is checked asynchronously while editing.
56 The user is in full command of the editor, and the prover refrains from
57 locking portions of the buffer.
59 \item Prover feedback works via colors, boxes, squiggly underline,
60 hyperlinks, popup windows, icons, clickable output, all based on semantic
61 markup produced by Isabelle in the background.
63 \item Using the mouse together with the modifier key @{verbatim CONTROL}
64 (Linux, Windows) or @{verbatim COMMAND} (Mac OS X) exposes additional
65 formal content via tooltips and/or hyperlinks.
67 \item Dockable panels (e.g. \emph{Output}, \emph{Symbols}) are managed as
68 independent windows by jEdit, which also allows multiple instances.
70 \item Formal output (in popups etc.) may be explored recursively, using
71 the same techniques as in the editor source buffer.
73 \item The prover process and source files are managed on the editor side.
74 The prover operates on timeless and stateless document content via
77 \item Plugin options of jEdit (for the \emph{Isabelle} plugin) give access
78 to a selection of Isabelle/Scala options and its persistence preferences,
79 usually with immediate effect on the prover back-end or editor front-end.
81 \item The logic image of the prover session may be specified within
82 Isabelle/jEdit, but this requires restart. The new image is provided
83 automatically by the Isabelle build process.
89 chapter {* Prover IDE functionality *}
91 section {* Isabelle symbols and fonts *}
94 Isabelle supports infinitely many symbols:
98 @{text "\<alpha>"}, @{text "\<beta>"}, @{text "\<gamma>"}, @{text "\<dots>"} \\
99 @{text "\<forall>"}, @{text "\<exists>"}, @{text "\<or>"}, @{text "\<and>"}, @{text "\<longrightarrow>"}, @{text "\<longleftrightarrow>"}, @{text "\<dots>"} \\
100 @{text "\<le>"}, @{text "\<ge>"}, @{text "\<sqinter>"}, @{text "\<squnion>"}, @{text "\<dots>"} \\
101 @{text "\<aleph>"}, @{text "\<triangle>"}, @{text "\<nabla>"}, @{text "\<dots>"} \\
102 @{verbatim "\<foo>"}, @{verbatim "\<bar>"}, @{verbatim "\<baz>"}, @{text "\<dots>"} \\
106 A default mapping relates some Isabelle symbols to Unicode points (see
107 @{file "$ISABELLE_HOME/etc/symbols"} and @{verbatim
108 "$ISABELLE_HOME_USER/etc/symbols"}.
110 The \emph{IsabelleText} font ensures that Unicode points are actually seen
111 on the screen (or printer).
116 \item use the \emph{Symbols} dockable window
117 \item copy/paste from decoded source files
118 \item copy/paste from prover output
119 \item completion provided by Isabelle plugin, e.g.\
123 \textbf{symbol} & \textbf{abbreviation} & \textbf{backslash escape} \\[1ex]
125 @{text "\<lambda>"} & @{verbatim "%"} & @{verbatim "\\lambda"} \\
126 @{text "\<Rightarrow>"} & @{verbatim "=>"} & @{verbatim "\\Rightarrow"} \\
127 @{text "\<Longrightarrow>"} & @{verbatim "==>"} & @{verbatim "\\Longrightarrow"} \\
129 @{text "\<And>"} & @{verbatim "!!"} & @{verbatim "\\And"} \\
130 @{text "\<equiv>"} & @{verbatim "=="} & @{verbatim "\\equiv"} \\
132 @{text "\<forall>"} & @{verbatim "!"} & @{verbatim "\\forall"} \\
133 @{text "\<exists>"} & @{verbatim "?"} & @{verbatim "\\exists"} \\
134 @{text "\<longrightarrow>"} & @{verbatim "-->"} & @{verbatim "\\longrightarrow"} \\
135 @{text "\<and>"} & @{verbatim "&"} & @{verbatim "\\and"} \\
136 @{text "\<or>"} & @{verbatim "|"} & @{verbatim "\\or"} \\
137 @{text "\<not>"} & @{verbatim "~"} & @{verbatim "\\not"} \\
138 @{text "\<noteq>"} & @{verbatim "~="} & @{verbatim "\\noteq"} \\
139 @{text "\<in>"} & @{verbatim ":"} & @{verbatim "\\in"} \\
140 @{text "\<notin>"} & @{verbatim "~:"} & @{verbatim "\\notin"} \\
148 \item The above abbreviations refer to the input method. The logical
149 notation provides ASCII alternatives that often coincide, but deviate
152 \item Generic jEdit abbreviations or plugins perform similar source
153 replacement operations; this works for Isabelle as long as the Unicode
154 sequences coincide with the symbol mapping.
156 \item Raw Unicode characters within prover source files should be
157 restricted to informal parts, e.g.\ to write text in non-latin alphabets.
158 Mathematical symbols should be defined via the official rendering tables.
162 \paragraph{Control symbols.} There are some special control symbols to
163 modify the style of a \emph{single} symbol (without nesting). Control
164 symbols may be applied to a region of selected text, either using the
165 \emph{Symbols} dockable window or keyboard shortcuts.
169 \textbf{symbol} & style & keyboard shortcure \\
170 @{verbatim "\<sup>"} & superscript & @{verbatim "C+e UP"} \\
171 @{verbatim "\<sub>"} & subscript & @{verbatim "C+e DOWN"} \\
172 @{verbatim "\<bold>"} & bold face & @{verbatim "C+e RIGHT"} \\
173 & reset & @{verbatim "C+e LEFT"} \\
178 section {* Text completion *}
181 Text completion works via some light-weight GUI popup, which is triggered by
182 keyboard events during the normal editing process in the main jEdit text
183 area and a few additional text fields. The popup interprets special keys:
184 @{verbatim TAB}, @{verbatim ESCAPE}, @{verbatim UP}, @{verbatim DOWN},
185 @{verbatim PAGE_UP}, @{verbatim PAGE_DOWN}. All other key events are passed
186 to the jEdit text area --- this allows to ignore unwanted completions most
187 of the time and continue typing quickly.
189 Various Isabelle plugin options control the popup behavior and immediate
190 insertion into buffer.
192 Isabelle Symbols are completed in backslashed forms, e.g. @{verbatim
193 "\\"}@{verbatim "forall"} or @{verbatim "\<forall>"} that both produce the Isabelle
194 symbol @{text "\<forall>"} in its Unicode rendering. Alternatively, symbol
195 abbreviations may be used as specified in @{file
196 "$ISABELLE_HOME/etc/symbols"}.
198 \emph{Explicit completion} works via standard jEdit shortcut @{verbatim
199 "C+b"}, which is remapped to action @{verbatim "isabelle.complete"}, with a
200 fall-back on regular @{verbatim "complete-word"} for non-Isabelle buffers.
202 \emph{Implicit completion} works via keyboard input on text area, with popup
203 or immediate insertion into buffer. Plain words require at least 3
204 characters to be completed.
206 \emph{Immediate completion} means the (unique) replacement text is inserted
207 into the buffer without popup. This mode ignores plain words and requires
208 more than one characters for symbol abbreviations. Otherwise it falls back
213 chapter {* Known problems and workarounds *}
218 \item \textbf{Problem:} Keyboard shortcuts @{verbatim "C+PLUS"} and
219 @{verbatim "C+MINUS"} for adjusting the editor font size depend on
220 platform details and national keyboards.
222 \textbf{Workaround:} Use numeric keypad or rebind keys in the
223 jEdit Shortcuts options dialog.
225 \item \textbf{Problem:} Lack of dependency management for auxiliary files
226 that contribute to a theory (e.g.\ @{command ML_file}).
228 \textbf{Workaround:} Re-load files manually within the prover.
230 \item \textbf{Problem:} Odd behavior of some diagnostic commands with
231 global side-effects, like writing a physical file.
233 \textbf{Workaround:} Avoid such commands.
235 \item \textbf{Problem:} No way to delete document nodes from the overall
236 collection of theories.
238 \textbf{Workaround:} Restart whole Isabelle/jEdit session in worst-case
241 \item \textbf{Problem:} Linux: some desktop environments with extreme
242 animation effects may disrupt Java 7 window placement and/or keyboard
245 \textbf{Workaround:} Disable such effects.
247 \item \textbf{Problem:} Linux: some X11 window managers that are not
248 ``re-parenting'' cause problems with additional windows opened by the Java
249 VM. This affects either historic or neo-minimalistic window managers like
250 ``@{verbatim awesome}'' or ``@{verbatim xmonad}''.
252 \textbf{Workaround:} Use regular re-parenting window manager.
254 \item \textbf{Problem:} The Mac OS X keyboard shortcut @{verbatim
255 "COMMAND+COMMA"} for Preferences is in conflict with the jEdit default
256 binding for @{verbatim "quick-search"}.
258 \textbf{Workaround:} Remap in jEdit manually according to national
259 keyboard, e.g.\ @{verbatim "COMMAND+SLASH"} on English ones.
261 \item \textbf{Problem:} Mac OS X: Java 7 is officially supported on Lion
262 and Mountain Lion, but not Snow Leopard. It usually works on the latter,
263 although with a small risk of instabilities.
265 \textbf{Workaround:} Update to OS X Mountain Lion, or later.