author wenzelm
Mon Mar 25 17:21:26 2019 +0100 (4 months ago)
changeset 69981 3dced198b9ec
parent 69854 cc0b3e177b49
child 70062 e7a01bbe789b
permissions -rw-r--r--
more strict AFP properties;
     1 (*:maxLineLen=78:*)
     3 theory JEdit
     4 imports Base
     5 begin
     7 chapter \<open>Introduction\<close>
     9 section \<open>Concepts and terminology\<close>
    11 text \<open>
    12   Isabelle/jEdit is a Prover IDE that integrates \<^emph>\<open>parallel proof checking\<close>
    13   @{cite "Wenzel:2009" and "Wenzel:2013:ITP"} with \<^emph>\<open>asynchronous user
    14   interaction\<close> @{cite "Wenzel:2010" and "Wenzel:2012:UITP-EPTCS" and
    15   "Wenzel:2014:ITP-PIDE" and "Wenzel:2014:UITP"}, based on a document-oriented
    16   approach to \<^emph>\<open>continuous proof processing\<close> @{cite "Wenzel:2011:CICM" and
    17   "Wenzel:2012"}. Many concepts and system components are fit together in
    18   order to make this work. The main building blocks are as follows.
    20     \<^descr>[Isabelle/ML] is the implementation and extension language of Isabelle,
    21     see also @{cite "isabelle-implementation"}. It is integrated into the
    22     logical context of Isabelle/Isar and allows to manipulate logical entities
    23     directly. Arbitrary add-on tools may be implemented for object-logics such
    24     as Isabelle/HOL.
    26     \<^descr>[Isabelle/Scala] is the system programming language of Isabelle. It
    27     extends the pure logical environment of Isabelle/ML towards the outer
    28     world of graphical user interfaces, text editors, IDE frameworks, web
    29     services, SSH servers, SQL databases etc. Special infrastructure allows to
    30     transfer algebraic datatypes and formatted text easily between ML and
    31     Scala, using asynchronous protocol commands.
    33     \<^descr>[PIDE] is a general framework for Prover IDEs based on Isabelle/Scala. It
    34     is built around a concept of parallel and asynchronous document
    35     processing, which is supported natively by the parallel proof engine that
    36     is implemented in Isabelle/ML. The traditional prover command loop is
    37     given up; instead there is direct support for editing of source text, with
    38     rich formal markup for GUI rendering.
    40     \<^descr>[jEdit] is a sophisticated text editor\<^footnote>\<open>\<^url>\<open>\<close>\<close>
    41     implemented in Java\<^footnote>\<open>\<^url>\<open>\<close>\<close>. It is easily extensible by
    42     plugins written in any language that works on the JVM. In the context of
    43     Isabelle this is always Scala\<^footnote>\<open>\<^url>\<open>\<close>\<close>.
    45     \<^descr>[Isabelle/jEdit] is the main application of the PIDE framework and the
    46     default user-interface for Isabelle. It targets both beginners and
    47     experts. Technically, Isabelle/jEdit consists of the original jEdit code
    48     base with minimal patches and a special plugin for Isabelle. This is
    49     integrated as a desktop application for the main operating system
    50     families: Linux, Windows, Mac OS X.
    52   End-users of Isabelle download and run a standalone application that exposes
    53   jEdit as a text editor on the surface. Thus there is occasionally a tendency
    54   to apply the name ``jEdit'' to any of the Isabelle Prover IDE aspects,
    55   without proper differentiation. When discussing these PIDE building blocks
    56   in public forums, mailing lists, or even scientific publications, it is
    57   particularly important to distinguish Isabelle/ML versus Standard ML,
    58   Isabelle/Scala versus Scala, Isabelle/jEdit versus jEdit.
    59 \<close>
    62 section \<open>The Isabelle/jEdit Prover IDE\<close>
    64 text \<open>
    65   \begin{figure}[!htb]
    66   \begin{center}
    67   \includegraphics[scale=0.333]{isabelle-jedit}
    68   \end{center}
    69   \caption{The Isabelle/jEdit Prover IDE}
    70   \label{fig:isabelle-jedit}
    71   \end{figure}
    73   Isabelle/jEdit (\figref{fig:isabelle-jedit}) consists of some plugins for
    74   the jEdit text editor, while preserving its general look-and-feel as far as
    75   possible. The main plugin is called ``Isabelle'' and has its own menu
    76   \<^emph>\<open>Plugins~/ Isabelle\<close> with access to several actions and add-on panels (see
    77   also \secref{sec:dockables}), as well as \<^emph>\<open>Plugins~/ Plugin Options~/
    78   Isabelle\<close> (see also \secref{sec:options}).
    80   The options allow to specify a logic session name, but the same selector is
    81   also accessible in the \<^emph>\<open>Theories\<close> panel (\secref{sec:theories}). After
    82   startup of the Isabelle plugin, the selected logic session image is provided
    83   automatically by the Isabelle build tool @{cite "isabelle-system"}: if it is
    84   absent or outdated wrt.\ its sources, the build process updates it within
    85   the running text editor. Prover IDE functionality is fully activated after
    86   successful termination of the build process. A failure may require changing
    87   some options and restart of the Isabelle plugin or application. Changing the
    88   logic session, or the underlying ML system platform (32\,bit versus 64\,bit)
    89   requires a restart of the whole application to take effect.
    91   \<^medskip>
    92   The main job of the Prover IDE is to manage sources and their changes,
    93   taking the logical structure as a formal document into account (see also
    94   \secref{sec:document-model}). The editor and the prover are connected
    95   asynchronously in a lock-free manner. The prover is free to organize the
    96   checking of the formal text in parallel on multiple cores, and provides
    97   feedback via markup, which is rendered in the editor via colors, boxes,
    98   squiggly underlines, hyperlinks, popup windows, icons, clickable output etc.
   100   Using the mouse together with the modifier key \<^verbatim>\<open>CONTROL\<close> (Linux, Windows)
   101   or \<^verbatim>\<open>COMMAND\<close> (Mac OS X) exposes formal content via tooltips and/or
   102   hyperlinks (see also \secref{sec:tooltips-hyperlinks}). Output (in popups
   103   etc.) may be explored recursively, using the same techniques as in the
   104   editor source buffer.
   106   Thus the Prover IDE gives an impression of direct access to formal content
   107   of the prover within the editor, but in reality only certain aspects are
   108   exposed, according to the possibilities of the prover and its add-on tools.
   109 \<close>
   112 subsection \<open>Documentation\<close>
   114 text \<open>
   115   The \<^emph>\<open>Documentation\<close> panel of Isabelle/jEdit provides access to some example
   116   theory files and the standard Isabelle documentation. PDF files are opened
   117   by regular desktop operations of the underlying platform. The section
   118   ``Original jEdit Documentation'' contains the original \<^emph>\<open>User's Guide\<close> of
   119   this sophisticated text editor. The same is accessible via the \<^verbatim>\<open>Help\<close> menu
   120   or \<^verbatim>\<open>F1\<close> keyboard shortcut, using the built-in HTML viewer of Java/Swing.
   121   The latter also includes \<^emph>\<open>Frequently Asked Questions\<close> and documentation of
   122   individual plugins.
   124   Most of the information about jEdit is relevant for Isabelle/jEdit as well,
   125   but users need to keep in mind that defaults sometimes differ, and the
   126   official jEdit documentation does not know about the Isabelle plugin with
   127   its support for continuous checking of formal source text: jEdit is a plain
   128   text editor, but Isabelle/jEdit is a Prover IDE.
   129 \<close>
   132 subsection \<open>Plugins\<close>
   134 text \<open>
   135   The \<^emph>\<open>Plugin Manager\<close> of jEdit allows to augment editor functionality by JVM
   136   modules (jars) that are provided by the central plugin repository, which is
   137   accessible via various mirror sites.
   139   Connecting to the plugin server-infrastructure of the jEdit project allows
   140   to update bundled plugins or to add further functionality. This needs to be
   141   done with the usual care for such an open bazaar of contributions. Arbitrary
   142   combinations of add-on features are apt to cause problems. It is advisable
   143   to start with the default configuration of Isabelle/jEdit and develop some
   144   sense how it is meant to work, before loading too many other plugins.
   146   \<^medskip>
   147   The \<^emph>\<open>Isabelle\<close> plugin is responsible for the main Prover IDE functionality
   148   of Isabelle/jEdit: it manages the prover session in the background. A few
   149   additional plugins are bundled with Isabelle/jEdit for convenience or out of
   150   necessity, notably \<^emph>\<open>Console\<close> with its \<^emph>\<open>Scala\<close> sub-plugin
   151   (\secref{sec:scala-console}) and \<^emph>\<open>SideKick\<close> with some Isabelle-specific
   152   parsers for document tree structure (\secref{sec:sidekick}). The
   153   \<^emph>\<open>Navigator\<close> plugin is particularly important for hyperlinks within the
   154   formal document-model (\secref{sec:tooltips-hyperlinks}). Further plugins
   155   (e.g.\ \<^emph>\<open>ErrorList\<close>, \<^emph>\<open>Code2HTML\<close>) are included to saturate the dependencies
   156   of bundled plugins, but have no particular use in Isabelle/jEdit.
   157 \<close>
   160 subsection \<open>Options \label{sec:options}\<close>
   162 text \<open>
   163   Both jEdit and Isabelle have distinctive management of persistent options.
   165   Regular jEdit options are accessible via the dialogs \<^emph>\<open>Utilities~/ Global
   166   Options\<close> or \<^emph>\<open>Plugins~/ Plugin Options\<close>, with a second chance to flip the
   167   two within the central options dialog. Changes are stored in \<^path>\<open>$JEDIT_SETTINGS/properties\<close> and \<^path>\<open>$JEDIT_SETTINGS/keymaps\<close>.
   169   Isabelle system options are managed by Isabelle/Scala and changes are stored
   170   in \<^path>\<open>$ISABELLE_HOME_USER/etc/preferences\<close>, independently of
   171   other jEdit properties. See also @{cite "isabelle-system"}, especially the
   172   coverage of sessions and command-line tools like @{tool build} or @{tool
   173   options}.
   175   Those Isabelle options that are declared as \<^verbatim>\<open>public\<close> are configurable in
   176   Isabelle/jEdit via \<^emph>\<open>Plugin Options~/ Isabelle~/ General\<close>. Moreover, there
   177   are various options for rendering document content, which are configurable
   178   via \<^emph>\<open>Plugin Options~/ Isabelle~/ Rendering\<close>. Thus \<^emph>\<open>Plugin Options~/
   179   Isabelle\<close> in jEdit provides a view on a subset of Isabelle system options.
   180   Note that some of these options affect general parameters that are relevant
   181   outside Isabelle/jEdit as well, e.g.\ @{system_option threads} or
   182   @{system_option parallel_proofs} for the Isabelle build tool @{cite
   183   "isabelle-system"}, but it is possible to use the settings variable
   184   @{setting ISABELLE_BUILD_OPTIONS} to change defaults for batch builds
   185   without affecting the Prover IDE.
   187   The jEdit action @{action_def isabelle.options} opens the options dialog for
   188   the Isabelle plugin; it can be mapped to editor GUI elements as usual.
   190   \<^medskip>
   191   Options are usually loaded on startup and saved on shutdown of
   192   Isabelle/jEdit. Editing the generated \<^path>\<open>$JEDIT_SETTINGS/properties\<close>
   193   or \<^path>\<open>$ISABELLE_HOME_USER/etc/preferences\<close> manually while the
   194   application is running may cause surprise due to lost updates!
   195 \<close>
   198 subsection \<open>Keymaps\<close>
   200 text \<open>
   201   Keyboard shortcuts are managed as a separate concept of \<^emph>\<open>keymap\<close> that is
   202   configurable via \<^emph>\<open>Global Options~/ Shortcuts\<close>. The \<^verbatim>\<open>imported\<close> keymap is
   203   derived from the initial environment of properties that is available at the
   204   first start of the editor; afterwards the keymap file takes precedence and
   205   is no longer affected by change of default properties.
   207   Users may change their keymap later, but this may lead to conflicts with
   208   \<^verbatim>\<open>shortcut\<close> properties in \<^file>\<open>$JEDIT_HOME/src/jEdit.props\<close>.
   210   The action @{action_def "isabelle.keymap-merge"} helps to resolve pending
   211   Isabelle keymap changes that are in conflict with the current jEdit keymap;
   212   while non-conflicting changes are applied implicitly. This action is
   213   automatically invoked on Isabelle/jEdit startup.
   214 \<close>
   217 section \<open>Command-line invocation \label{sec:command-line}\<close>
   219 text \<open>
   220   Isabelle/jEdit is normally invoked as a single-instance desktop application,
   221   based on platform-specific executables for Linux, Windows, Mac OS X.
   223   It is also possible to invoke the Prover IDE on the command-line, with some
   224   extra options and environment settings. The command-line usage of @{tool_def
   225   jedit} is as follows:
   226   @{verbatim [display]
   227 \<open>Usage: isabelle jedit [OPTIONS] [FILES ...]
   229   Options are:
   230     -A NAME      ancestor session for options -R and -S (default: parent)
   231     -D NAME=X    set JVM system property
   232     -J OPTION    add JVM runtime option
   233                  (default $JEDIT_JAVA_SYSTEM_OPTIONS $JEDIT_JAVA_OPTIONS)
   234     -R NAME      build image with requirements from other sessions
   235     -S NAME      like option -R, with focus on selected session
   236     -b           build only
   237     -d DIR       include session directory
   238     -f           fresh build
   239     -i NAME      include session in name-space of theories
   240     -j OPTION    add jEdit runtime option
   241                  (default $JEDIT_OPTIONS)
   242     -l NAME      logic image name
   243     -m MODE      add print mode for output
   244     -n           no build of session image on startup
   245     -p CMD       ML process command prefix (process policy)
   246     -s           system build mode for session image (system_heaps=true)
   247     -u           user build mode for session image (system_heaps=false)
   249   Start jEdit with Isabelle plugin setup and open FILES
   250   (default "$USER_HOME/Scratch.thy" or ":" for empty buffer).\<close>}
   252   The \<^verbatim>\<open>-l\<close> option specifies the session name of the logic image to be used
   253   for proof processing. Additional session root directories may be included
   254   via option \<^verbatim>\<open>-d\<close> to augment the session name space (see also @{cite
   255   "isabelle-system"}). By default, the specified image is checked and built on
   256   demand, but option \<^verbatim>\<open>-n\<close> bypasses the implicit build process for the
   257   selected session image. Options \<^verbatim>\<open>-s\<close> and \<^verbatim>\<open>-u\<close> override the default system
   258   option @{system_option system_heaps}: this determines where to store the
   259   session image of @{tool build}.
   261   The \<^verbatim>\<open>-R\<close> option builds an auxiliary logic image with all theories from
   262   other sessions that are not already present in its parent; it also opens the
   263   session \<^verbatim>\<open>ROOT\<close> entry in the editor to facilitate editing of the main
   264   session. The \<^verbatim>\<open>-S\<close> option is like \<^verbatim>\<open>-R\<close>, with a focus on the selected
   265   session and its descendants: the namespace of accessible theories is
   266   restricted accordingly. This reduces startup time for big projects, notably
   267   the ``Archive of Formal Proofs''. The \<^verbatim>\<open>-A\<close> option specifies and alternative
   268   ancestor session for options \<^verbatim>\<open>-R\<close> and \<^verbatim>\<open>-S\<close>: this allows to restructure the
   269   hierarchy of session images on the spot.
   271   The \<^verbatim>\<open>-i\<close> option includes additional sessions into the name-space of
   272   theories: multiple occurrences are possible.
   274   The \<^verbatim>\<open>-m\<close> option specifies additional print modes for the prover process.
   275   Note that the system option @{system_option_ref jedit_print_mode} allows to
   276   do the same persistently (e.g.\ via the \<^emph>\<open>Plugin Options\<close> dialog of
   277   Isabelle/jEdit), without requiring command-line invocation.
   279   The \<^verbatim>\<open>-J\<close> and \<^verbatim>\<open>-j\<close> options pass additional low-level options to the JVM or
   280   jEdit, respectively. The defaults are provided by the Isabelle settings
   281   environment @{cite "isabelle-system"}, but note that these only work for the
   282   command-line tool described here, and not the regular application.
   284   The \<^verbatim>\<open>-D\<close> option allows to define JVM system properties; this is passed
   285   directly to the underlying \<^verbatim>\<open>java\<close> process.
   287   The \<^verbatim>\<open>-b\<close> and \<^verbatim>\<open>-f\<close> options control the self-build mechanism of
   288   Isabelle/jEdit. This is only relevant for building from sources, which also
   289   requires an auxiliary \<^verbatim>\<open>jedit_build\<close> component from
   290   \<^url>\<open>\<close>. The official Isabelle release
   291   already includes a pre-built version of Isabelle/jEdit.
   293   \<^bigskip>
   294   It is also possible to connect to an already running Isabelle/jEdit process
   295   via @{tool_def jedit_client}:
   296   @{verbatim [display]
   297 \<open>Usage: isabelle jedit_client [OPTIONS] [FILES ...]
   299   Options are:
   300     -c           only check presence of server
   301     -n           only report server name
   302     -s NAME      server name (default Isabelle)
   304   Connect to already running Isabelle/jEdit instance and open FILES\<close>}
   306   The \<^verbatim>\<open>-c\<close> option merely checks the presence of the server, producing a
   307   process return code accordingly.
   309   The \<^verbatim>\<open>-n\<close> option reports the server name, and the \<^verbatim>\<open>-s\<close> option provides a
   310   different server name. The default server name is the official distribution
   311   name (e.g.\ \<^verbatim>\<open>Isabelle2018\<close>). Thus @{tool jedit_client} can connect to the
   312   Isabelle desktop application without further options.
   314   The \<^verbatim>\<open>-p\<close> option allows to override the implicit default of the system
   315   option @{system_option_ref ML_process_policy} for ML processes started by
   316   the Prover IDE, e.g. to control CPU affinity on multiprocessor systems.
   318   The JVM system property \<^verbatim>\<open>isabelle.jedit_server\<close> provides a different server
   319   name, e.g.\ use \<^verbatim>\<open>isabelle jedit -Disabelle.jedit_server=\<close>\<open>name\<close> and
   320   \<^verbatim>\<open>isabelle jedit_client -s\<close>~\<open>name\<close> to connect later on.
   321 \<close>
   324 section \<open>GUI rendering\<close>
   326 subsection \<open>Look-and-feel \label{sec:look-and-feel}\<close>
   328 text \<open>
   329   jEdit is a Java/AWT/Swing application with the ambition to support
   330   ``native'' look-and-feel on all platforms, within the limits of what Oracle
   331   as Java provider and major operating system distributors allow (see also
   332   \secref{sec:problems}).
   334   Isabelle/jEdit enables platform-specific look-and-feel by default as
   335   follows.
   337     \<^descr>[Linux:] The platform-independent \<^emph>\<open>Metal\<close> is used by default.
   339     The Linux-specific \<^emph>\<open>GTK+\<close> often works as well, but the overall GTK theme
   340     and options need to be selected to suite Java/AWT/Swing. Note that Java
   341     Virtual Machine has no direct influence of GTK rendering.
   343     \<^descr>[Windows:] Regular \<^emph>\<open>Windows\<close> is used by default.
   345     \<^descr>[Mac OS X:] Regular \<^emph>\<open>Mac OS X\<close> is used by default.
   347     The bundled \<^emph>\<open>MacOSX\<close> plugin provides various functions that are expected
   348     from applications on that particular platform: quit from menu or dock,
   349     preferences menu, drag-and-drop of text files on the application,
   350     full-screen mode for main editor windows. It is advisable to have the
   351     \<^emph>\<open>MacOSX\<close> plugin enabled all the time on that platform.
   353   Users may experiment with different Swing look-and-feels, but need to keep
   354   in mind that this extra variance of GUI functionality often causes problems.
   355   The platform-independent \<^emph>\<open>Metal\<close> and \<^emph>\<open>Nimbus\<close> should always work on all
   356   platforms, although they are technically and stylistically outdated. The
   357   historic \<^emph>\<open>CDE/Motif\<close> should be ignored.
   359   Changing the look-and-feel in \<^emph>\<open>Global Options~/ Appearance\<close> may update the
   360   GUI only partially: proper restart of Isabelle/jEdit is usually required.
   361 \<close>
   364 subsection \<open>Displays with very high resolution \label{sec:hdpi}\<close>
   366 text \<open>
   367   In distant past, displays with $1024 \times 768$ or $1280 \times 1024$
   368   pixels were considered ``high resolution'' and bitmap fonts with 12 or 14
   369   pixels as adequate for text rendering. After 2016, we have routinely seen
   370   much higher resolutions, e.g. ``Full HD'' at $1920 \times 1080$ pixels or
   371   ``Ultra HD'' / ``4K'' at $3840 \times 2160$.
   373   GUI frameworks are usually lagging behind, with hard-wired icon sizes and
   374   tiny fonts. Java and jEdit do provide reasonable support for very high
   375   resolution, but this requires manual adjustments as described below.
   377   \<^medskip>
   378   The \<^bold>\<open>operating-system\<close> usually provides some configuration for global
   379   scaling of text fonts, e.g.\ $120\%$--$250\%$ on Windows. This impacts
   380   regular GUI elements, when used with native look-and-feel: Linux \<^emph>\<open>GTK+\<close>,
   381   \<^emph>\<open>Windows\<close>, \<^emph>\<open>Mac OS X\<close>, respectively. Alternatively, it is possible to use
   382   the platform-independent \<^emph>\<open>Metal\<close> look-and-feel and readjust its main font
   383   sizes via jEdit options explained below. The Isabelle/jEdit \<^bold>\<open>application\<close>
   384   provides further options to adjust font sizes in particular GUI elements.
   385   Here is a summary of all relevant font properties:
   387     \<^item> \<^emph>\<open>Global Options / Text Area / Text font\<close>: the main text area font,
   388     which is also used as reference point for various derived font sizes,
   389     e.g.\ the \<^emph>\<open>Output\<close> (\secref{sec:output}) and \<^emph>\<open>State\<close>
   390     (\secref{sec:state-output}) panels.
   392     \<^item> \<^emph>\<open>Global Options / Gutter / Gutter font\<close>: the font for the gutter area
   393     left of the main text area, e.g.\ relevant for display of line numbers
   394     (disabled by default).
   396     \<^item> \<^emph>\<open>Global Options / Appearance / Button, menu and label font\<close> as well as
   397     \<^emph>\<open>List and text field font\<close>: this specifies the primary and secondary font
   398     for the \<^emph>\<open>Metal\<close> look-and-feel (\secref{sec:look-and-feel}).
   400     \<^item> \<^emph>\<open>Plugin Options / Isabelle / General / Reset Font Size\<close>: the main text
   401     area font size for action @{action_ref "isabelle.reset-font-size"}, e.g.\
   402     relevant for quick scaling like in common web browsers.
   404     \<^item> \<^emph>\<open>Plugin Options / Console / General / Font\<close>: the console window font,
   405     e.g.\ relevant for Isabelle/Scala command-line.
   407   In \figref{fig:isabelle-jedit-hdpi} the \<^emph>\<open>Metal\<close> look-and-feel is configured
   408   with custom fonts at 30 pixels, and the main text area and console at 36
   409   pixels. This leads to decent rendering quality, despite the old-fashioned
   410   appearance of \<^emph>\<open>Metal\<close>.
   412   \begin{figure}[!htb]
   413   \begin{center}
   414   \includegraphics[width=\textwidth]{isabelle-jedit-hdpi}
   415   \end{center}
   416   \caption{Metal look-and-feel with custom fonts for very high resolution}
   417   \label{fig:isabelle-jedit-hdpi}
   418   \end{figure}
   419 \<close>
   422 chapter \<open>Augmented jEdit functionality\<close>
   424 section \<open>Dockable windows \label{sec:dockables}\<close>
   426 text \<open>
   427   In jEdit terminology, a \<^emph>\<open>view\<close> is an editor window with one or more \<^emph>\<open>text
   428   areas\<close> that show the content of one or more \<^emph>\<open>buffers\<close>. A regular view may
   429   be surrounded by \<^emph>\<open>dockable windows\<close> that show additional information in
   430   arbitrary format, not just text; a \<^emph>\<open>plain view\<close> does not allow dockables.
   431   The \<^emph>\<open>dockable window manager\<close> of jEdit organizes these dockable windows,
   432   either as \<^emph>\<open>floating\<close> windows, or \<^emph>\<open>docked\<close> panels within one of the four
   433   margins of the view. There may be any number of floating instances of some
   434   dockable window, but at most one docked instance; jEdit actions that address
   435   \<^emph>\<open>the\<close> dockable window of a particular kind refer to the unique docked
   436   instance.
   438   Dockables are used routinely in jEdit for important functionality like
   439   \<^emph>\<open>HyperSearch Results\<close> or the \<^emph>\<open>File System Browser\<close>. Plugins often provide
   440   a central dockable to access their main functionality, which may be opened
   441   by the user on demand. The Isabelle/jEdit plugin takes this approach to the
   442   extreme: its plugin menu provides the entry-points to many panels that are
   443   managed as dockable windows. Some important panels are docked by default,
   444   e.g.\ \<^emph>\<open>Documentation\<close>, \<^emph>\<open>State\<close>, \<^emph>\<open>Theories\<close> \<^emph>\<open>Output\<close>, \<^emph>\<open>Query\<close>. The user
   445   can change this arrangement easily and persistently.
   447   Compared to plain jEdit, dockable window management in Isabelle/jEdit is
   448   slightly augmented according to the the following principles:
   450   \<^item> Floating windows are dependent on the main window as \<^emph>\<open>dialog\<close> in
   451   the sense of Java/AWT/Swing. Dialog windows always stay on top of the view,
   452   which is particularly important in full-screen mode. The desktop environment
   453   of the underlying platform may impose further policies on such dependent
   454   dialogs, in contrast to fully independent windows, e.g.\ some window
   455   management functions may be missing.
   457   \<^item> Keyboard focus of the main view vs.\ a dockable window is carefully
   458   managed according to the intended semantics, as a panel mainly for output or
   459   input. For example, activating the \<^emph>\<open>Output\<close> (\secref{sec:output}) or State
   460   (\secref{sec:state-output}) panel via the dockable window manager returns
   461   keyboard focus to the main text area, but for \<^emph>\<open>Query\<close> (\secref{sec:query})
   462   or \<^emph>\<open>Sledgehammer\<close> \secref{sec:sledgehammer} the focus is given to the main
   463   input field of that panel.
   465   \<^item> Panels that provide their own text area for output have an additional
   466   dockable menu item \<^emph>\<open>Detach\<close>. This produces an independent copy of the
   467   current output as a floating \<^emph>\<open>Info\<close> window, which displays that content
   468   independently of ongoing changes of the PIDE document-model. Note that
   469   Isabelle/jEdit popup windows (\secref{sec:tooltips-hyperlinks}) provide a
   470   similar \<^emph>\<open>Detach\<close> operation as an icon.
   471 \<close>
   474 section \<open>Isabelle symbols \label{sec:symbols}\<close>
   476 text \<open>
   477   Isabelle sources consist of \<^emph>\<open>symbols\<close> that extend plain ASCII to allow
   478   infinitely many mathematical symbols within the formal sources. This works
   479   without depending on particular encodings and varying Unicode
   480   standards.\<^footnote>\<open>Raw Unicode characters within formal sources would compromise
   481   portability and reliability in the face of changing interpretation of
   482   special features of Unicode, such as Combining Characters or Bi-directional
   483   Text.\<close> See @{cite "Wenzel:2011:CICM"}.
   485   For the prover back-end, formal text consists of ASCII characters that are
   486   grouped according to some simple rules, e.g.\ as plain ``\<^verbatim>\<open>a\<close>'' or symbolic
   487   ``\<^verbatim>\<open>\<alpha>\<close>''. For the editor front-end, a certain subset of symbols is rendered
   488   physically via Unicode glyphs, in order to show ``\<^verbatim>\<open>\<alpha>\<close>'' as ``\<open>\<alpha>\<close>'', for
   489   example. This symbol interpretation is specified by the Isabelle system
   490   distribution in \<^file>\<open>$ISABELLE_HOME/etc/symbols\<close> and may be augmented by the
   491   user in \<^path>\<open>$ISABELLE_HOME_USER/etc/symbols\<close>.
   493   The appendix of @{cite "isabelle-isar-ref"} gives an overview of the
   494   standard interpretation of finitely many symbols from the infinite
   495   collection. Uninterpreted symbols are displayed literally, e.g.\
   496   ``\<^verbatim>\<open>\<foobar>\<close>''. Overlap of Unicode characters used in symbol
   497   interpretation with informal ones (which might appear e.g.\ in comments)
   498   needs to be avoided. Raw Unicode characters within prover source files
   499   should be restricted to informal parts, e.g.\ to write text in non-latin
   500   alphabets in comments.
   501 \<close>
   503 paragraph \<open>Encoding.\<close>
   505 text \<open>Technically, the Unicode interpretation of Isabelle symbols is an
   506   \<^emph>\<open>encoding\<close> called \<^verbatim>\<open>UTF-8-Isabelle\<close> in jEdit (\<^emph>\<open>not\<close> in the underlying
   507   JVM). It is provided by the Isabelle Base plugin and enabled by default for
   508   all source files in Isabelle/jEdit.
   510   Sometimes such defaults are reset accidentally, or malformed UTF-8 sequences
   511   in the text force jEdit to fall back on a different encoding like
   512   \<^verbatim>\<open>ISO-8859-15\<close>. In that case, verbatim ``\<^verbatim>\<open>\<alpha>\<close>'' will be shown in the text
   513   buffer instead of its Unicode rendering ``\<open>\<alpha>\<close>''. The jEdit menu operation
   514   \<^emph>\<open>File~/ Reload with Encoding~/ UTF-8-Isabelle\<close> helps to resolve such
   515   problems (after repairing malformed parts of the text).
   517   If the loaded text already contains Unicode sequences that are in conflict
   518   with the Isabelle symbol encoding, the fallback-encoding UTF-8 is used and
   519   Isabelle symbols remain in literal \<^verbatim>\<open>\<symbol>\<close> form. The jEdit menu
   520   operation \<^emph>\<open>Utilities~/ Buffer Options~/ Character encoding\<close> allows to
   521   enforce the UTF-8-Isabelle, but this will also change original Unicode
   522   text into Isabelle symbols when saving the file!
   523 \<close>
   525 paragraph \<open>Font.\<close>
   526 text \<open>Correct rendering via Unicode requires a font that contains glyphs for
   527   the corresponding codepoints. There are also various unusual symbols with
   528   particular purpose in Isabelle, e.g.\ control symbols and very long arrows.
   529   Isabelle/jEdit prefers its own font collection \<^verbatim>\<open>Isabelle DejaVu\<close>, which
   530   ensures that all standard Isabelle symbols are shown on the screen (or
   531   printer) as expected.
   533   Note that a Java/AWT/Swing application can load additional fonts only if
   534   they are not installed on the operating system already! Outdated versions of
   535   Isabelle fonts that happen to be provided by the operating system prevent
   536   Isabelle/jEdit to use its bundled version. This could lead to missing glyphs
   537   (black rectangles), when the system version of a font is older than the
   538   application version. This problem can be avoided by refraining to
   539   ``install'' any version of \<^verbatim>\<open>IsabelleText\<close> in the first place, although it
   540   might be tempting to use the same font in other applications.
   542   HTML pages generated by Isabelle refer to the same Isabelle fonts as a
   543   server-side resource. Thus a web-browser can use that without requiring a
   544   locally installed copy.
   545 \<close>
   547 paragraph \<open>Input methods.\<close>
   548 text \<open>In principle, Isabelle/jEdit could delegate the problem to produce
   549   Isabelle symbols in their Unicode rendering to the underlying operating
   550   system and its \<^emph>\<open>input methods\<close>. Regular jEdit also provides various ways to
   551   work with \<^emph>\<open>abbreviations\<close> to produce certain non-ASCII characters. Since
   552   none of these standard input methods work satisfactorily for the
   553   mathematical characters required for Isabelle, various specific
   554   Isabelle/jEdit mechanisms are provided.
   556   This is a summary for practically relevant input methods for Isabelle
   557   symbols.
   559   \<^enum> The \<^emph>\<open>Symbols\<close> panel: some GUI buttons allow to insert certain symbols in
   560   the text buffer. There are also tooltips to reveal the official Isabelle
   561   representation with some additional information about \<^emph>\<open>symbol
   562   abbreviations\<close> (see below).
   564   \<^enum> Copy/paste from decoded source files: text that is rendered as Unicode
   565   already can be re-used to produce further text. This also works between
   566   different applications, e.g.\ Isabelle/jEdit and some web browser or mail
   567   client, as long as the same Unicode interpretation of Isabelle symbols is
   568   used.
   570   \<^enum> Copy/paste from prover output within Isabelle/jEdit. The same principles
   571   as for text buffers apply, but note that \<^emph>\<open>copy\<close> in secondary Isabelle/jEdit
   572   windows works via the keyboard shortcuts \<^verbatim>\<open>C+c\<close> or \<^verbatim>\<open>C+INSERT\<close>, while jEdit
   573   menu actions always refer to the primary text area!
   575   \<^enum> Completion provided by the Isabelle plugin (see \secref{sec:completion}).
   576   Isabelle symbols have a canonical name and optional abbreviations. This can
   577   be used with the text completion mechanism of Isabelle/jEdit, to replace a
   578   prefix of the actual symbol like \<^verbatim>\<open>\<lambda>\<close>, or its name preceded by backslash
   579   \<^verbatim>\<open>\lambda\<close>, or its ASCII abbreviation \<^verbatim>\<open>%\<close> by the Unicode rendering.
   581   The following table is an extract of the information provided by the
   582   standard \<^file>\<open>$ISABELLE_HOME/etc/symbols\<close> file:
   584   \<^medskip>
   585   \begin{tabular}{lll}
   586     \<^bold>\<open>symbol\<close> & \<^bold>\<open>name with backslash\<close> & \<^bold>\<open>abbreviation\<close> \\\hline
   587     \<open>\<lambda>\<close> & \<^verbatim>\<open>\lambda\<close> & \<^verbatim>\<open>%\<close> \\
   588     \<open>\<Rightarrow>\<close> & \<^verbatim>\<open>\Rightarrow\<close> & \<^verbatim>\<open>=>\<close> \\
   589     \<open>\<Longrightarrow>\<close> & \<^verbatim>\<open>\Longrightarrow\<close> & \<^verbatim>\<open>==>\<close> \\[0.5ex]
   590     \<open>\<And>\<close> & \<^verbatim>\<open>\And\<close> & \<^verbatim>\<open>!!\<close> \\
   591     \<open>\<equiv>\<close> & \<^verbatim>\<open>\equiv\<close> & \<^verbatim>\<open>==\<close> \\[0.5ex]
   592     \<open>\<forall>\<close> & \<^verbatim>\<open>\forall\<close> & \<^verbatim>\<open>!\<close> \\
   593     \<open>\<exists>\<close> & \<^verbatim>\<open>\exists\<close> & \<^verbatim>\<open>?\<close> \\
   594     \<open>\<longrightarrow>\<close> & \<^verbatim>\<open>\longrightarrow\<close> & \<^verbatim>\<open>-->\<close> \\
   595     \<open>\<and>\<close> & \<^verbatim>\<open>\and\<close> & \<^verbatim>\<open>&\<close> \\
   596     \<open>\<or>\<close> & \<^verbatim>\<open>\or\<close> & \<^verbatim>\<open>|\<close> \\
   597     \<open>\<not>\<close> & \<^verbatim>\<open>\not\<close> & \<^verbatim>\<open>~\<close> \\
   598     \<open>\<noteq>\<close> & \<^verbatim>\<open>\noteq\<close> & \<^verbatim>\<open>~=\<close> \\
   599     \<open>\<in>\<close> & \<^verbatim>\<open>\in\<close> & \<^verbatim>\<open>:\<close> \\
   600     \<open>\<notin>\<close> & \<^verbatim>\<open>\notin\<close> & \<^verbatim>\<open>~:\<close> \\
   601   \end{tabular}
   602   \<^medskip>
   604   Note that the above abbreviations refer to the input method. The logical
   605   notation provides ASCII alternatives that often coincide, but sometimes
   606   deviate. This occasionally causes user confusion with old-fashioned Isabelle
   607   source that use ASCII replacement notation like \<^verbatim>\<open>!\<close> or \<^verbatim>\<open>ALL\<close> directly in
   608   the text.
   610   On the other hand, coincidence of symbol abbreviations with ASCII
   611   replacement syntax syntax helps to update old theory sources via explicit
   612   completion (see also \<^verbatim>\<open>C+b\<close> explained in \secref{sec:completion}).
   613 \<close>
   615 paragraph \<open>Control symbols.\<close>
   616 text \<open>There are some special control symbols to modify the display style of a
   617   single symbol (without nesting). Control symbols may be applied to a region
   618   of selected text, either using the \<^emph>\<open>Symbols\<close> panel or keyboard shortcuts or
   619   jEdit actions. These editor operations produce a separate control symbol for
   620   each symbol in the text, in order to make the whole text appear in a certain
   621   style.
   623   \<^medskip>
   624   \begin{tabular}{llll}
   625     \<^bold>\<open>style\<close> & \<^bold>\<open>symbol\<close> & \<^bold>\<open>shortcut\<close> & \<^bold>\<open>action\<close> \\\hline
   626     superscript & \<^verbatim>\<open>\<^sup>\<close> & \<^verbatim>\<open>C+e UP\<close> & @{action_ref "isabelle.control-sup"} \\
   627     subscript & \<^verbatim>\<open>\<^sub>\<close> & \<^verbatim>\<open>C+e DOWN\<close> & @{action_ref "isabelle.control-sub"} \\
   628     bold face & \<^verbatim>\<open>\<^bold>\<close> & \<^verbatim>\<open>C+e RIGHT\<close> & @{action_ref "isabelle.control-bold"} \\
   629     emphasized & \<^verbatim>\<open>\<^emph>\<close> & \<^verbatim>\<open>C+e LEFT\<close> & @{action_ref "isabelle.control-emph"} \\
   630     reset & & \<^verbatim>\<open>C+e BACK_SPACE\<close> & @{action_ref "isabelle.control-reset"} \\
   631   \end{tabular}
   632   \<^medskip>
   634   To produce a single control symbol, it is also possible to complete on
   635   \<^verbatim>\<open>\sup\<close>, \<^verbatim>\<open>\sub\<close>, \<^verbatim>\<open>\bold\<close>, \<^verbatim>\<open>\emph\<close> as for regular symbols.
   637   The emphasized style only takes effect in document output (when used with a
   638   cartouche), but not in the editor.
   639 \<close>
   642 section \<open>Scala console \label{sec:scala-console}\<close>
   644 text \<open>
   645   The \<^emph>\<open>Console\<close> plugin manages various shells (command interpreters), e.g.\
   646   \<^emph>\<open>BeanShell\<close>, which is the official jEdit scripting language, and the
   647   cross-platform \<^emph>\<open>System\<close> shell. Thus the console provides similar
   648   functionality than the Emacs buffers \<^verbatim>\<open>*scratch*\<close> and \<^verbatim>\<open>*shell*\<close>.
   650   Isabelle/jEdit extends the repertoire of the console by \<^emph>\<open>Scala\<close>, which is
   651   the regular Scala toplevel loop running inside the same JVM process as
   652   Isabelle/jEdit itself. This means the Scala command interpreter has access
   653   to the JVM name space and state of the running Prover IDE application. The
   654   default environment imports the full content of packages \<^verbatim>\<open>isabelle\<close> and
   655   \<^verbatim>\<open>isabelle.jedit\<close>.
   657   For example, \<^verbatim>\<open>PIDE\<close> refers to the Isabelle/jEdit plugin object, and \<^verbatim>\<open>view\<close>
   658   to the current editor view of jEdit. The Scala expression
   659   \<^verbatim>\<open>PIDE.snapshot(view)\<close> makes a PIDE document snapshot of the current buffer
   660   within the current editor view.
   662   This helps to explore Isabelle/Scala functionality interactively. Some care
   663   is required to avoid interference with the internals of the running
   664   application.
   665 \<close>
   668 section \<open>File-system access\<close>
   670 text \<open>
   671   File specifications in jEdit follow various formats and conventions
   672   according to \<^emph>\<open>Virtual File Systems\<close>, which may be also provided by
   673   additional plugins. This allows to access remote files via the \<^verbatim>\<open>http:\<close>
   674   protocol prefix, for example. Isabelle/jEdit attempts to work with the
   675   file-system model of jEdit as far as possible. In particular, theory sources
   676   are passed directly from the editor to the prover, without indirection via
   677   physical files.
   679   Despite the flexibility of URLs in jEdit, local files are particularly
   680   important and are accessible without protocol prefix. The file path notation
   681   is that of the Java Virtual Machine on the underlying platform. On Windows
   682   the preferred form uses backslashes, but happens to accept forward slashes
   683   like Unix/POSIX as well. Further differences arise due to Windows drive
   684   letters and network shares.
   686   The Java notation for files needs to be distinguished from the one of
   687   Isabelle, which uses POSIX notation with forward slashes on \<^emph>\<open>all\<close>
   688   platforms. Isabelle/ML on Windows uses Unix-style path notation, too, and
   689   driver letter representation as in Cygwin (e.g.\ \<^verbatim>\<open>/cygdrive/c\<close>). Moreover,
   690   environment variables from the Isabelle process may be used freely, e.g.\
   691   \<^file>\<open>$ISABELLE_HOME/etc/symbols\<close> or \<^file>\<open>$POLYML_HOME/README\<close>. There are special
   692   shortcuts: \<^dir>\<open>~\<close> for \<^dir>\<open>$USER_HOME\<close> and \<^dir>\<open>~~\<close> for \<^dir>\<open>$ISABELLE_HOME\<close>.
   694   \<^medskip>
   695   Since jEdit happens to support environment variables within file
   696   specifications as well, it is natural to use similar notation within the
   697   editor, e.g.\ in the file-browser. This does not work in full generality,
   698   though, due to the bias of jEdit towards platform-specific notation and of
   699   Isabelle towards POSIX. Moreover, the Isabelle settings environment is not
   700   yet active when starting Isabelle/jEdit via its standard application
   701   wrapper, in contrast to @{tool jedit} run from the command line
   702   (\secref{sec:command-line}).
   704   Isabelle/jEdit imitates important system settings within the Java process
   705   environment, in order to allow easy access to these important places from
   706   the editor: \<^verbatim>\<open>$ISABELLE_HOME\<close>, \<^verbatim>\<open>$ISABELLE_HOME_USER\<close>, \<^verbatim>\<open>$JEDIT_HOME\<close>,
   707   \<^verbatim>\<open>$JEDIT_SETTINGS\<close>. The file browser of jEdit also includes \<^emph>\<open>Favorites\<close> for
   708   these two important locations.
   710   \<^medskip>
   711   Path specifications in prover input or output usually include formal markup
   712   that turns it into a hyperlink (see also \secref{sec:tooltips-hyperlinks}).
   713   This allows to open the corresponding file in the text editor, independently
   714   of the path notation. If the path refers to a directory, the jEdit file
   715   browser is opened on it.
   717   Formally checked paths in prover input are subject to completion
   718   (\secref{sec:completion}): partial specifications are resolved via directory
   719   content and possible completions are offered in a popup.
   720 \<close>
   723 section \<open>Indentation\<close>
   725 text \<open>
   726   Isabelle/jEdit augments the existing indentation facilities of jEdit to take
   727   the structure of theory and proof texts into account. There is also special
   728   support for unstructured proof scripts.
   730     \<^descr>[Syntactic indentation] follows the outer syntax of Isabelle/Isar.
   732     Action @{action "indent-lines"} (shortcut \<^verbatim>\<open>C+i\<close>) indents the current line
   733     according to command keywords and some command substructure: this
   734     approximation may need further manual tuning.
   736     Action @{action "isabelle.newline"} (shortcut \<^verbatim>\<open>ENTER\<close>) indents the old
   737     and the new line according to command keywords only: this leads to precise
   738     alignment of the main Isar language elements. This depends on option
   739     @{system_option_def "jedit_indent_newline"} (enabled by default).
   741     Regular input (via keyboard or completion) indents the current line
   742     whenever an new keyword is emerging at the start of the line. This depends
   743     on option @{system_option_def "jedit_indent_input"} (enabled by default).
   745     \<^descr>[Semantic indentation] adds additional white space to unstructured proof
   746     scripts (\<^theory_text>\<open>apply\<close> etc.) via number of subgoals. This requires information
   747     of ongoing document processing and may thus lag behind, when the user is
   748     editing too quickly; see also option @{system_option_def
   749     "jedit_script_indent"} and @{system_option_def
   750     "jedit_script_indent_limit"}.
   752   The above options are accessible in the menu \<^emph>\<open>Plugins / Plugin Options /
   753   Isabelle / General\<close>. A prerequisite for advanced indentation is \<^emph>\<open>Utilities
   754   / Buffer Options / Automatic indentation\<close>: it needs to be set to \<^verbatim>\<open>full\<close>
   755   (default).
   756 \<close>
   759 section \<open>SideKick parsers \label{sec:sidekick}\<close>
   761 text \<open>
   762   The \<^emph>\<open>SideKick\<close> plugin provides some general services to display buffer
   763   structure in a tree view. Isabelle/jEdit provides SideKick parsers for its
   764   main mode for theory files, ML files, as well as some minor modes for the
   765   \<^verbatim>\<open>NEWS\<close> file (see \figref{fig:sidekick}), session \<^verbatim>\<open>ROOT\<close> files, system
   766   \<^verbatim>\<open>options\<close>, and Bib{\TeX} files (\secref{sec:bibtex}).
   768   \begin{figure}[!htb]
   769   \begin{center}
   770   \includegraphics[scale=0.333]{sidekick}
   771   \end{center}
   772   \caption{The Isabelle NEWS file with SideKick tree view}
   773   \label{fig:sidekick}
   774   \end{figure}
   776   The default SideKick parser for theory files is \<^verbatim>\<open>isabelle\<close>: it provides a
   777   tree-view on the formal document structure, with section headings at the top
   778   and formal specification elements at the bottom. The alternative parser
   779   \<^verbatim>\<open>isabelle-context\<close> shows nesting of context blocks according to \<^theory_text>\<open>begin \<dots>
   780   end\<close> structure.
   782   \<^medskip>
   783   Isabelle/ML files are structured according to semi-formal comments that are
   784   explained in @{cite "isabelle-implementation"}. This outline is turned into
   785   a tree-view by default, by using the \<^verbatim>\<open>isabelle-ml\<close> parser. There is also a
   786   folding mode of the same name, for hierarchic text folds within ML files.
   788   \<^medskip>
   789   The special SideKick parser \<^verbatim>\<open>isabelle-markup\<close> exposes the uninterpreted
   790   markup tree of the PIDE document model of the current buffer. This is
   791   occasionally useful for informative purposes, but the amount of displayed
   792   information might cause problems for large buffers.
   793 \<close>
   796 chapter \<open>Prover IDE functionality \label{sec:document-model}\<close>
   798 section \<open>Document model \label{sec:document-model}\<close>
   800 text \<open>
   801   The document model is central to the PIDE architecture: the editor and the
   802   prover have a common notion of structured source text with markup, which is
   803   produced by formal processing. The editor is responsible for edits of
   804   document source, as produced by the user. The prover is responsible for
   805   reports of document markup, as produced by its processing in the background.
   807   Isabelle/jEdit handles classic editor events of jEdit, in order to connect
   808   the physical world of the GUI (with its singleton state) to the mathematical
   809   world of multiple document versions (with timeless and stateless updates).
   810 \<close>
   813 subsection \<open>Editor buffers and document nodes \label{sec:buffer-node}\<close>
   815 text \<open>
   816   As a regular text editor, jEdit maintains a collection of \<^emph>\<open>buffers\<close> to
   817   store text files; each buffer may be associated with any number of visible
   818   \<^emph>\<open>text areas\<close>. Buffers are subject to an \<^emph>\<open>edit mode\<close> that is determined
   819   from the file name extension. The following modes are treated specifically
   820   in Isabelle/jEdit:
   822   \<^medskip>
   823   \begin{tabular}{lll}
   824   \<^bold>\<open>mode\<close> & \<^bold>\<open>file name\<close> & \<^bold>\<open>content\<close> \\\hline
   825   \<^verbatim>\<open>isabelle\<close> & \<^verbatim>\<open>*.thy\<close> & theory source \\
   826   \<^verbatim>\<open>isabelle-ml\<close> & \<^verbatim>\<open>*.ML\<close> & Isabelle/ML source \\
   827   \<^verbatim>\<open>sml\<close> & \<^verbatim>\<open>*.sml\<close> or \<^verbatim>\<open>*.sig\<close> & Standard ML source \\
   828   \<^verbatim>\<open>isabelle-root\<close> & \<^verbatim>\<open>ROOT\<close> & session root \\
   829   \<^verbatim>\<open>isabelle-options\<close> & & Isabelle options \\
   830   \<^verbatim>\<open>isabelle-news\<close> & & Isabelle NEWS \\
   831   \end{tabular}
   832   \<^medskip>
   834   All jEdit buffers are automatically added to the PIDE document-model as
   835   \<^emph>\<open>document nodes\<close>. The overall document structure is defined by the theory
   836   nodes in two dimensions:
   838     \<^enum> via \<^bold>\<open>theory imports\<close> that are specified in the \<^emph>\<open>theory header\<close> using
   839     concrete syntax of the @{command_ref theory} command @{cite
   840     "isabelle-isar-ref"};
   842     \<^enum> via \<^bold>\<open>auxiliary files\<close> that are included into a theory by \<^emph>\<open>load
   843     commands\<close>, notably @{command_ref ML_file} and @{command_ref SML_file}
   844     @{cite "isabelle-isar-ref"}.
   846   In any case, source files are managed by the PIDE infrastructure: the
   847   physical file-system only plays a subordinate role. The relevant version of
   848   source text is passed directly from the editor to the prover, using internal
   849   communication channels.
   850 \<close>
   853 subsection \<open>Theories \label{sec:theories}\<close>
   855 text \<open>
   856   The \<^emph>\<open>Theories\<close> panel (see also \figref{fig:theories}) provides an overview
   857   of the status of continuous checking of theory nodes within the document
   858   model.
   860   \begin{figure}[!htb]
   861   \begin{center}
   862   \includegraphics[scale=0.333]{theories}
   863   \end{center}
   864   \caption{Theories panel with an overview of the document-model, and jEdit
   865   text areas as editable views on some of the document nodes}
   866   \label{fig:theories}
   867   \end{figure}
   869   Theory imports are resolved automatically by the PIDE document model: all
   870   required files are loaded and stored internally, without the need to open
   871   corresponding jEdit buffers. Opening or closing editor buffers later on has
   872   no direct impact on the formal document content: it only affects visibility.
   874   In contrast, auxiliary files (e.g.\ from @{command ML_file} commands) are
   875   \<^emph>\<open>not\<close> resolved within the editor by default, but the prover process takes
   876   care of that. This may be changed by enabling the system option
   877   @{system_option jedit_auto_resolve}: it ensures that all files are uniformly
   878   provided by the editor.
   880   \<^medskip>
   881   The visible \<^emph>\<open>perspective\<close> of Isabelle/jEdit is defined by the collective
   882   view on theory buffers via open text areas. The perspective is taken as a
   883   hint for document processing: the prover ensures that those parts of a
   884   theory where the user is looking are checked, while other parts that are
   885   presently not required are ignored. The perspective is changed by opening or
   886   closing text area windows, or scrolling within a window.
   888   The \<^emph>\<open>Theories\<close> panel provides some further options to influence the process
   889   of continuous checking: it may be switched off globally to restrict the
   890   prover to superficial processing of command syntax. It is also possible to
   891   indicate theory nodes as \<^emph>\<open>required\<close> for continuous checking: this means
   892   such nodes and all their imports are always processed independently of the
   893   visibility status (if continuous checking is enabled). Big theory libraries
   894   that are marked as required can have significant impact on performance!
   896   The \<^emph>\<open>Purge\<close> button restricts the document model to theories that are
   897   required for open editor buffers: inaccessible theories are removed and will
   898   be rechecked when opened or imported later.
   900   \<^medskip>
   901   Formal markup of checked theory content is turned into GUI rendering, based
   902   on a standard repertoire known from mainstream IDEs for programming
   903   languages: colors, icons, highlighting, squiggly underlines, tooltips,
   904   hyperlinks etc. For outer syntax of Isabelle/Isar there is some traditional
   905   syntax-highlighting via static keywords and tokenization within the editor;
   906   this buffer syntax is determined from theory imports. In contrast, the
   907   painting of inner syntax (term language etc.)\ uses semantic information
   908   that is reported dynamically from the logical context. Thus the prover can
   909   provide additional markup to help the user to understand the meaning of
   910   formal text, and to produce more text with some add-on tools (e.g.\
   911   information messages with \<^emph>\<open>sendback\<close> markup by automated provers or
   912   disprovers in the background). \<close>
   915 subsection \<open>Auxiliary files \label{sec:aux-files}\<close>
   917 text \<open>
   918   Special load commands like @{command_ref ML_file} and @{command_ref
   919   SML_file} @{cite "isabelle-isar-ref"} refer to auxiliary files within some
   920   theory. Conceptually, the file argument of the command extends the theory
   921   source by the content of the file, but its editor buffer may be loaded~/
   922   changed~/ saved separately. The PIDE document model propagates changes of
   923   auxiliary file content to the corresponding load command in the theory, to
   924   update and process it accordingly: changes of auxiliary file content are
   925   treated as changes of the corresponding load command.
   927   \<^medskip>
   928   As a concession to the massive amount of ML files in Isabelle/HOL itself,
   929   the content of auxiliary files is only added to the PIDE document-model on
   930   demand, the first time when opened explicitly in the editor. There are
   931   further tricks to manage markup of ML files, such that Isabelle/HOL may be
   932   edited conveniently in the Prover IDE on small machines with only 8\,GB of
   933   main memory. Using \<^verbatim>\<open>Pure\<close> as logic session image, the exploration may start
   934   at the top \<^file>\<open>$ISABELLE_HOME/src/HOL/Main.thy\<close> or the bottom
   935   \<^file>\<open>$ISABELLE_HOME/src/HOL/HOL.thy\<close>, for example. It is also possible to
   936   explore the Isabelle/Pure bootstrap process (a virtual copy) by opening
   937   \<^file>\<open>$ISABELLE_HOME/src/Pure/ROOT.ML\<close> like a theory in the Prover IDE.
   939   Initially, before an auxiliary file is opened in the editor, the prover
   940   reads its content from the physical file-system. After the file is opened
   941   for the first time in the editor, e.g.\ by following the hyperlink
   942   (\secref{sec:tooltips-hyperlinks}) for the argument of its @{command
   943   ML_file} command, the content is taken from the jEdit buffer.
   945   The change of responsibility from prover to editor counts as an update of
   946   the document content, so subsequent theory sources need to be re-checked.
   947   When the buffer is closed, the responsibility remains to the editor: the
   948   file may be opened again without causing another document update.
   950   A file that is opened in the editor, but its theory with the load command is
   951   not, is presently inactive in the document model. A file that is loaded via
   952   multiple load commands is associated to an arbitrary one: this situation is
   953   morally unsupported and might lead to confusion.
   955   \<^medskip>
   956   Output that refers to an auxiliary file is combined with that of the
   957   corresponding load command, and shown whenever the file or the command are
   958   active (see also \secref{sec:output}).
   960   Warnings, errors, and other useful markup is attached directly to the
   961   positions in the auxiliary file buffer, in the manner of standard IDEs. By
   962   using the load command @{command SML_file} as explained in
   963   \<^file>\<open>$ISABELLE_HOME/src/Tools/SML/Examples.thy\<close>, Isabelle/jEdit may be used as
   964   fully-featured IDE for Standard ML, independently of theory or proof
   965   development: the required theory merely serves as some kind of project file
   966   for a collection of SML source modules.
   967 \<close>
   970 section \<open>Output \label{sec:output}\<close>
   972 text \<open>
   973   Prover output consists of \<^emph>\<open>markup\<close> and \<^emph>\<open>messages\<close>. Both are directly
   974   attached to the corresponding positions in the original source text, and
   975   visualized in the text area, e.g.\ as text colours for free and bound
   976   variables, or as squiggly underlines for warnings, errors etc.\ (see also
   977   \figref{fig:output}). In the latter case, the corresponding messages are
   978   shown by hovering with the mouse over the highlighted text --- although in
   979   many situations the user should already get some clue by looking at the
   980   position of the text highlighting, without seeing the message body itself.
   982   \begin{figure}[!htb]
   983   \begin{center}
   984   \includegraphics[scale=0.333]{output}
   985   \end{center}
   986   \caption{Multiple views on prover output: gutter with icon, text area with
   987   popup, text overview column, \<^emph>\<open>Theories\<close> panel, \<^emph>\<open>Output\<close> panel}
   988   \label{fig:output}
   989   \end{figure}
   991   The ``gutter'' on the left-hand-side of the text area uses icons to
   992   provide a summary of the messages within the adjacent text line. Message
   993   priorities are used to prefer errors over warnings, warnings over
   994   information messages; other output is ignored.
   996   The ``text overview column'' on the right-hand-side of the text area uses
   997   similar information to paint small rectangles for the overall status of the
   998   whole text buffer. The graphics is scaled to fit the logical buffer length
   999   into the given window height. Mouse clicks on the overview area move the
  1000   cursor approximately to the corresponding text line in the buffer.
  1002   The \<^emph>\<open>Theories\<close> panel provides another course-grained overview, but without
  1003   direct correspondence to text positions. The coloured rectangles represent
  1004   the amount of messages of a certain kind (warnings, errors, etc.) and the
  1005   execution status of commands. The border of each rectangle indicates the
  1006   overall status of processing: a thick border means it is \<^emph>\<open>finished\<close> or
  1007   \<^emph>\<open>failed\<close> (with color for errors). A double-click on one of the theory
  1008   entries with their status overview opens the corresponding text buffer,
  1009   without moving the cursor to a specific point.
  1011   \<^medskip>
  1012   The \<^emph>\<open>Output\<close> panel displays prover messages that correspond to a given
  1013   command, within a separate window. The cursor position in the presently
  1014   active text area determines the prover command whose cumulative message
  1015   output is appended and shown in that window (in canonical order according to
  1016   the internal execution of the command). There are also control elements to
  1017   modify the update policy of the output wrt.\ continued editor movements:
  1018   \<^emph>\<open>Auto update\<close> and \<^emph>\<open>Update\<close>. This is particularly useful for multiple
  1019   instances of the \<^emph>\<open>Output\<close> panel to look at different situations.
  1020   Alternatively, the panel can be turned into a passive \<^emph>\<open>Info\<close> window via the
  1021   \<^emph>\<open>Detach\<close> menu item.
  1023   Proof state is handled separately (\secref{sec:state-output}), but it is
  1024   also possible to tick the corresponding checkbox to append it to regular
  1025   output (\figref{fig:output-including-state}). This is a globally persistent
  1026   option: it affects all open panels and future editor sessions.
  1028   \begin{figure}[!htb]
  1029   \begin{center}
  1030   \includegraphics[scale=0.333]{output-including-state}
  1031   \end{center}
  1032   \caption{Proof state display within the regular output panel}
  1033   \label{fig:output-including-state}
  1034   \end{figure}
  1036   \<^medskip>
  1037   Following the IDE principle, regular messages are attached to the original
  1038   source in the proper place and may be inspected on demand via popups. This
  1039   excludes messages that are somehow internal to the machinery of proof
  1040   checking, notably \<^emph>\<open>proof state\<close> and \<^emph>\<open>tracing\<close>.
  1042   In any case, the same display technology is used for small popups and big
  1043   output windows. The formal text contains markup that may be explored
  1044   recursively via further popups and hyperlinks (see
  1045   \secref{sec:tooltips-hyperlinks}), or clicked directly to initiate certain
  1046   actions (see \secref{sec:auto-tools} and \secref{sec:sledgehammer}).
  1047 \<close>
  1050 section \<open>Proof state \label{sec:state-output}\<close>
  1052 text \<open>
  1053   The main purpose of the Prover IDE is to help the user editing proof
  1054   documents, with ongoing formal checking by the prover in the background.
  1055   This can be done to some extent in the main text area alone, especially for
  1056   well-structured Isar proofs.
  1058   Nonetheless, internal proof state needs to be inspected in many situations
  1059   of exploration and ``debugging''. The \<^emph>\<open>State\<close> panel shows exclusively such
  1060   proof state messages without further distraction, while all other messages
  1061   are displayed in \<^emph>\<open>Output\<close> (\secref{sec:output}).
  1062   \Figref{fig:output-and-state} shows a typical GUI layout where both panels
  1063   are open.
  1065   \begin{figure}[!htb]
  1066   \begin{center}
  1067   \includegraphics[scale=0.333]{output-and-state}
  1068   \end{center}
  1069   \caption{Separate proof state display (right) and other output (bottom).}
  1070   \label{fig:output-and-state}
  1071   \end{figure}
  1073   Another typical arrangement has more than one \<^emph>\<open>State\<close> panel open (as
  1074   floating windows), with \<^emph>\<open>Auto update\<close> disabled to look at an old situation
  1075   while the proof text in the vicinity is changed. The \<^emph>\<open>Update\<close> button
  1076   triggers an explicit one-shot update; this operation is also available via
  1077   the action @{action "isabelle.update-state"} (keyboard shortcut \<^verbatim>\<open>S+ENTER\<close>).
  1079   On small screens, it is occasionally useful to have all messages
  1080   concatenated in the regular \<^emph>\<open>Output\<close> panel, e.g.\ see
  1081   \figref{fig:output-including-state}.
  1083   \<^medskip>
  1084   The mechanics of \<^emph>\<open>Output\<close> versus \<^emph>\<open>State\<close> are slightly different:
  1086     \<^item> \<^emph>\<open>Output\<close> shows information that is continuously produced and already
  1087     present when the GUI wants to show it. This is implicitly controlled by
  1088     the visible perspective on the text.
  1090     \<^item> \<^emph>\<open>State\<close> initiates a real-time query on demand, with a full round trip
  1091     including a fresh print operation on the prover side. This is controlled
  1092     explicitly when the cursor is moved to the next command (\<^emph>\<open>Auto update\<close>)
  1093     or the \<^emph>\<open>Update\<close> operation is triggered.
  1095   This can make a difference in GUI responsibility and resource usage within
  1096   the prover process. Applications with very big proof states that are only
  1097   inspected in isolation work better with the \<^emph>\<open>State\<close> panel.
  1098 \<close>
  1101 section \<open>Query \label{sec:query}\<close>
  1103 text \<open>
  1104   The \<^emph>\<open>Query\<close> panel provides various GUI forms to request extra information
  1105   from the prover, as a replacement of old-style diagnostic commands like
  1106   @{command find_theorems}. There are input fields and buttons for a
  1107   particular query command, with output in a dedicated text area.
  1109   The main query modes are presented as separate tabs: \<^emph>\<open>Find Theorems\<close>,
  1110   \<^emph>\<open>Find Constants\<close>, \<^emph>\<open>Print Context\<close>, e.g.\ see \figref{fig:query}. As usual
  1111   in jEdit, multiple \<^emph>\<open>Query\<close> windows may be active at the same time: any
  1112   number of floating instances, but at most one docked instance (which is used
  1113   by default).
  1115   \begin{figure}[!htb]
  1116   \begin{center}
  1117   \includegraphics[scale=0.333]{query}
  1118   \end{center}
  1119   \caption{An instance of the Query panel: find theorems}
  1120   \label{fig:query}
  1121   \end{figure}
  1123   \<^medskip>
  1124   The following GUI elements are common to all query modes:
  1126     \<^item> The spinning wheel provides feedback about the status of a pending query
  1127     wrt.\ the evaluation of its context and its own operation.
  1129     \<^item> The \<^emph>\<open>Apply\<close> button attaches a fresh query invocation to the current
  1130     context of the command where the cursor is pointing in the text.
  1132     \<^item> The \<^emph>\<open>Search\<close> field allows to highlight query output according to some
  1133     regular expression, in the notation that is commonly used on the Java
  1134     platform.\<^footnote>\<open>\<^url>\<open>\<close>\<close>
  1135     This may serve as an additional visual filter of the result.
  1137     \<^item> The \<^emph>\<open>Zoom\<close> box controls the font size of the output area.
  1139   All query operations are asynchronous: there is no need to wait for the
  1140   evaluation of the document for the query context, nor for the query
  1141   operation itself. Query output may be detached as independent \<^emph>\<open>Info\<close>
  1142   window, using a menu operation of the dockable window manager. The printed
  1143   result usually provides sufficient clues about the original query, with some
  1144   hyperlink to its context (via markup of its head line).
  1145 \<close>
  1148 subsection \<open>Find theorems\<close>
  1150 text \<open>
  1151   The \<^emph>\<open>Query\<close> panel in \<^emph>\<open>Find Theorems\<close> mode retrieves facts from the theory
  1152   or proof context matching all of given criteria in the \<^emph>\<open>Find\<close> text field. A
  1153   single criterion has the following syntax:
  1155   \<^rail>\<open>
  1156     ('-'?) ('name' ':' @{syntax name} | 'intro' | 'elim' | 'dest' |
  1157       'solves' | 'simp' ':' @{syntax term} | @{syntax term})
  1158   \<close>
  1160   See also the Isar command @{command_ref find_theorems} in @{cite
  1161   "isabelle-isar-ref"}.
  1162 \<close>
  1165 subsection \<open>Find constants\<close>
  1167 text \<open>
  1168   The \<^emph>\<open>Query\<close> panel in \<^emph>\<open>Find Constants\<close> mode prints all constants whose type
  1169   meets all of the given criteria in the \<^emph>\<open>Find\<close> text field. A single
  1170   criterion has the following syntax:
  1172   \<^rail>\<open>
  1173     ('-'?)
  1174       ('name' ':' @{syntax name} | 'strict' ':' @{syntax type} | @{syntax type})
  1175   \<close>
  1177   See also the Isar command @{command_ref find_consts} in @{cite
  1178   "isabelle-isar-ref"}.
  1179 \<close>
  1182 subsection \<open>Print context\<close>
  1184 text \<open>
  1185   The \<^emph>\<open>Query\<close> panel in \<^emph>\<open>Print Context\<close> mode prints information from the
  1186   theory or proof context, or proof state. See also the Isar commands
  1187   @{command_ref print_context}, @{command_ref print_cases}, @{command_ref
  1188   print_term_bindings}, @{command_ref print_theorems}, described in @{cite
  1189   "isabelle-isar-ref"}.
  1190 \<close>
  1193 section \<open>Tooltips and hyperlinks \label{sec:tooltips-hyperlinks}\<close>
  1195 text \<open>
  1196   Formally processed text (prover input or output) contains rich markup that
  1197   can be explored by using the \<^verbatim>\<open>CONTROL\<close> modifier key on Linux and Windows,
  1198   or \<^verbatim>\<open>COMMAND\<close> on Mac OS X. Hovering with the mouse while the modifier is
  1199   pressed reveals a \<^emph>\<open>tooltip\<close> (grey box over the text with a yellow popup)
  1200   and/or a \<^emph>\<open>hyperlink\<close> (black rectangle over the text with change of mouse
  1201   pointer); see also \figref{fig:tooltip}.
  1203   \begin{figure}[!htb]
  1204   \begin{center}
  1205   \includegraphics[scale=0.5]{popup1}
  1206   \end{center}
  1207   \caption{Tooltip and hyperlink for some formal entity}
  1208   \label{fig:tooltip}
  1209   \end{figure}
  1211   Tooltip popups use the same rendering technology as the main text area, and
  1212   further tooltips and/or hyperlinks may be exposed recursively by the same
  1213   mechanism; see \figref{fig:nested-tooltips}.
  1215   \begin{figure}[!htb]
  1216   \begin{center}
  1217   \includegraphics[scale=0.5]{popup2}
  1218   \end{center}
  1219   \caption{Nested tooltips over formal entities}
  1220   \label{fig:nested-tooltips}
  1221   \end{figure}
  1223   The tooltip popup window provides some controls to \<^emph>\<open>close\<close> or \<^emph>\<open>detach\<close> the
  1224   window, turning it into a separate \<^emph>\<open>Info\<close> window managed by jEdit. The
  1225   \<^verbatim>\<open>ESCAPE\<close> key closes \<^emph>\<open>all\<close> popups, which is particularly relevant when
  1226   nested tooltips are stacking up.
  1228   \<^medskip>
  1229   A black rectangle in the text indicates a hyperlink that may be followed by
  1230   a mouse click (while the \<^verbatim>\<open>CONTROL\<close> or \<^verbatim>\<open>COMMAND\<close> modifier key is still
  1231   pressed). Such jumps to other text locations are recorded by the
  1232   \<^emph>\<open>Navigator\<close> plugin, which is bundled with Isabelle/jEdit and enabled by
  1233   default. There are usually navigation arrows in the main jEdit toolbar.
  1235   Note that the link target may be a file that is itself not subject to formal
  1236   document processing of the editor session and thus prevents further
  1237   exploration: the chain of hyperlinks may end in some source file of the
  1238   underlying logic image, or within the ML bootstrap sources of Isabelle/Pure.
  1239 \<close>
  1242 section \<open>Formal scopes and semantic selection\<close>
  1244 text \<open>
  1245   Formal entities are semantically annotated in the source text as explained
  1246   in \secref{sec:tooltips-hyperlinks}. A \<^emph>\<open>formal scope\<close> consists of the
  1247   defining position with all its referencing positions. This correspondence is
  1248   highlighted in the text according to the cursor position, see also
  1249   \figref{fig:scope1}. Here the referencing positions are rendered with an
  1250   additional border, in reminiscence to a hyperlink: clicking there moves the
  1251   cursor to the original defining position.
  1253   \begin{figure}[!htb]
  1254   \begin{center}
  1255   \includegraphics[scale=0.5]{scope1}
  1256   \end{center}
  1257   \caption{Scope of formal entity: defining vs.\ referencing positions}
  1258   \label{fig:scope1}
  1259   \end{figure}
  1261   The action @{action_def ""} (shortcut \<^verbatim>\<open>CS+ENTER\<close>)
  1262   supports semantic selection of all occurrences of the formal entity at the
  1263   caret position. This facilitates systematic renaming, using regular jEdit
  1264   editing of a multi-selection, see also \figref{fig:scope2}.
  1266   \begin{figure}[!htb]
  1267   \begin{center}
  1268   \includegraphics[scale=0.5]{scope2}
  1269   \end{center}
  1270   \caption{The result of semantic selection and systematic renaming}
  1271   \label{fig:scope2}
  1272   \end{figure}
  1273 \<close>
  1276 section \<open>Completion \label{sec:completion}\<close>
  1278 text \<open>
  1279   Smart completion of partial input is the IDE functionality \<^emph>\<open>par
  1280   excellance\<close>. Isabelle/jEdit combines several sources of information to
  1281   achieve that. Despite its complexity, it should be possible to get some idea
  1282   how completion works by experimentation, based on the overview of completion
  1283   varieties in \secref{sec:completion-varieties}. The remaining subsections
  1284   explain concepts around completion more systematically.
  1286   \<^medskip>
  1287   \<^emph>\<open>Explicit completion\<close> is triggered by the action @{action_ref
  1288   "isabelle.complete"}, which is bound to the keyboard shortcut \<^verbatim>\<open>C+b\<close>, and
  1289   thus overrides the jEdit default for @{action_ref "complete-word"}.
  1291   \<^emph>\<open>Implicit completion\<close> hooks into the regular keyboard input stream of the
  1292   editor, with some event filtering and optional delays.
  1294   \<^medskip>
  1295   Completion options may be configured in \<^emph>\<open>Plugin Options~/ Isabelle~/
  1296   General~/ Completion\<close>. These are explained in further detail below, whenever
  1297   relevant. There is also a summary of options in
  1298   \secref{sec:completion-options}.
  1300   The asynchronous nature of PIDE interaction means that information from the
  1301   prover is delayed --- at least by a full round-trip of the document update
  1302   protocol. The default options already take this into account, with a
  1303   sufficiently long completion delay to speculate on the availability of all
  1304   relevant information from the editor and the prover, before completing text
  1305   immediately or producing a popup. Although there is an inherent danger of
  1306   non-deterministic behaviour due to such real-time parameters, the general
  1307   completion policy aims at determined results as far as possible.
  1308 \<close>
  1311 subsection \<open>Varieties of completion \label{sec:completion-varieties}\<close>
  1313 subsubsection \<open>Built-in templates\<close>
  1315 text \<open>
  1316   Isabelle is ultimately a framework of nested sub-languages of different
  1317   kinds and purposes. The completion mechanism supports this by the following
  1318   built-in templates:
  1320     \<^descr> \<^verbatim>\<open>`\<close> (single ASCII back-quote) or \<^verbatim>\<open>"\<close> (double ASCII quote) support
  1321     \<^emph>\<open>quotations\<close> via text cartouches. There are three selections, which are
  1322     always presented in the same order and do not depend on any context
  1323     information. The default choice produces a template ``\<open>\<open>\<box>\<close>\<close>'', where the
  1324     box indicates the cursor position after insertion; the other choices help
  1325     to repair the block structure of unbalanced text cartouches.
  1327     \<^descr> \<^verbatim>\<open>@{\<close> is completed to the template ``\<open>@{\<box>}\<close>'', where the box indicates
  1328     the cursor position after insertion. Here it is convenient to use the
  1329     wildcard ``\<^verbatim>\<open>__\<close>'' or a more specific name prefix to let semantic
  1330     completion of name-space entries propose antiquotation names.
  1332   With some practice, input of quoted sub-languages and antiquotations of
  1333   embedded languages should work fluently. Note that national keyboard layouts
  1334   might cause problems with back-quote as dead key, but double quote can be
  1335   used instead.
  1336 \<close>
  1339 subsubsection \<open>Syntax keywords\<close>
  1341 text \<open>
  1342   Syntax completion tables are determined statically from the keywords of the
  1343   ``outer syntax'' of the underlying edit mode: for theory files this is the
  1344   syntax of Isar commands according to the cumulative theory imports.
  1346   Keywords are usually plain words, which means the completion mechanism only
  1347   inserts them directly into the text for explicit completion
  1348   (\secref{sec:completion-input}), but produces a popup
  1349   (\secref{sec:completion-popup}) otherwise.
  1351   At the point where outer syntax keywords are defined, it is possible to
  1352   specify an alternative replacement string to be inserted instead of the
  1353   keyword itself. An empty string means to suppress the keyword altogether,
  1354   which is occasionally useful to avoid confusion, e.g.\ the rare keyword
  1355   @{command simproc_setup} vs.\ the frequent name-space entry \<open>simp\<close>.
  1356 \<close>
  1359 subsubsection \<open>Isabelle symbols\<close>
  1361 text \<open>
  1362   The completion tables for Isabelle symbols (\secref{sec:symbols}) are
  1363   determined statically from \<^file>\<open>$ISABELLE_HOME/etc/symbols\<close> and \<^path>\<open>$ISABELLE_HOME_USER/etc/symbols\<close> for each symbol specification as follows:
  1365   \<^medskip>
  1366   \begin{tabular}{ll}
  1367   \<^bold>\<open>completion entry\<close> & \<^bold>\<open>example\<close> \\\hline
  1368   literal symbol & \<^verbatim>\<open>\<forall>\<close> \\
  1369   symbol name with backslash & \<^verbatim>\<open>\\<close>\<^verbatim>\<open>forall\<close> \\
  1370   symbol abbreviation & \<^verbatim>\<open>ALL\<close> or \<^verbatim>\<open>!\<close> \\
  1371   \end{tabular}
  1372   \<^medskip>
  1374   When inserted into the text, the above examples all produce the same Unicode
  1375   rendering \<open>\<forall>\<close> of the underlying symbol \<^verbatim>\<open>\<forall>\<close>.
  1377   A symbol abbreviation that is a plain word, like \<^verbatim>\<open>ALL\<close>, is treated like a
  1378   syntax keyword. Non-word abbreviations like \<^verbatim>\<open>-->\<close> are inserted more
  1379   aggressively, except for single-character abbreviations like \<^verbatim>\<open>!\<close> above.
  1381   Completion via abbreviations like \<^verbatim>\<open>ALL\<close> or \<^verbatim>\<open>-->\<close> depends on the semantic
  1382   language context (\secref{sec:completion-context}). In contrast, backslash
  1383   sequences like \<^verbatim>\<open>\forall\<close> \<^verbatim>\<open>\<forall>\<close> are always possible, but require additional
  1384   interaction to confirm (via popup). This is important in ambiguous
  1385   situations, e.g.\ for Isabelle document source, which may contain formal
  1386   symbols or informal {\LaTeX} macros. Backslash sequences also help when
  1387   input is broken, and thus escapes its normal semantic context: e.g.\
  1388   antiquotations or string literals in ML, which do not allow arbitrary
  1389   backslash sequences.
  1391   Special symbols like \<^verbatim>\<open>\<comment>\<close> or control symbols like \<^verbatim>\<open>\<^cancel>\<close>,
  1392   \<^verbatim>\<open>\<^latex>\<close>, \<^verbatim>\<open>\<^binding>\<close> can have an argument: completing on a name
  1393   prefix offers a template with an empty cartouche. Thus completion of \<^verbatim>\<open>\co\<close>
  1394   or \<^verbatim>\<open>\ca\<close> allows to compose formal document comments quickly.\<^footnote>\<open>It is
  1395   customary to put a space between \<^verbatim>\<open>\<comment>\<close> and its argument, while
  1396   control symbols do \<^emph>\<open>not\<close> allow extra space here.\<close>
  1397 \<close>
  1400 subsubsection \<open>User-defined abbreviations\<close>
  1402 text \<open>
  1403   The theory header syntax supports abbreviations via the \<^theory_text>\<open>abbrevs\<close> keyword
  1404   @{cite "isabelle-isar-ref"}. This is a slight generalization of built-in
  1405   templates and abbreviations for Isabelle symbols, as explained above.
  1406   Examples may be found in the Isabelle sources, by searching for
  1407   ``\<^verbatim>\<open>abbrevs\<close>'' in \<^verbatim>\<open>*.thy\<close> files.
  1409   The \<^emph>\<open>Symbols\<close> panel shows the abbreviations that are available in the
  1410   current theory buffer (according to its \<^theory_text>\<open>imports\<close>) in the \<^verbatim>\<open>Abbrevs\<close> tab.
  1411 \<close>
  1414 subsubsection \<open>Name-space entries\<close>
  1416 text \<open>
  1417   This is genuine semantic completion, using information from the prover, so
  1418   it requires some delay. A \<^emph>\<open>failed name-space lookup\<close> produces an error
  1419   message that is annotated with a list of alternative names that are legal.
  1420   The list of results is truncated according to the system option
  1421   @{system_option_ref completion_limit}. The completion mechanism takes this
  1422   into account when collecting information on the prover side.
  1424   Already recognized names are \<^emph>\<open>not\<close> completed further, but completion may be
  1425   extended by appending a suffix of underscores. This provokes a failed
  1426   lookup, and another completion attempt while ignoring the underscores. For
  1427   example, in a name space where \<^verbatim>\<open>foo\<close> and \<^verbatim>\<open>foobar\<close> are known, the input
  1428   \<^verbatim>\<open>foo\<close> remains unchanged, but \<^verbatim>\<open>foo_\<close> may be completed to \<^verbatim>\<open>foo\<close> or
  1429   \<^verbatim>\<open>foobar\<close>.
  1431   The special identifier ``\<^verbatim>\<open>__\<close>'' serves as a wild-card for arbitrary
  1432   completion: it exposes the name-space content to the completion mechanism
  1433   (truncated according to @{system_option completion_limit}). This is
  1434   occasionally useful to explore an unknown name-space, e.g.\ in some
  1435   template.
  1436 \<close>
  1439 subsubsection \<open>File-system paths\<close>
  1441 text \<open>
  1442   Depending on prover markup about file-system paths in the source text, e.g.\
  1443   for the argument of a load command (\secref{sec:aux-files}), the completion
  1444   mechanism explores the directory content and offers the result as completion
  1445   popup. Relative path specifications are understood wrt.\ the \<^emph>\<open>master
  1446   directory\<close> of the document node (\secref{sec:buffer-node}) of the enclosing
  1447   editor buffer; this requires a proper theory, not an auxiliary file.
  1449   A suffix of slashes may be used to continue the exploration of an already
  1450   recognized directory name.
  1451 \<close>
  1454 subsubsection \<open>Spell-checking\<close>
  1456 text \<open>
  1457   The spell-checker combines semantic markup from the prover (regions of plain
  1458   words) with static dictionaries (word lists) that are known to the editor.
  1460   Unknown words are underlined in the text, using @{system_option_ref
  1461   spell_checker_color} (blue by default). This is not an error, but a hint to
  1462   the user that some action may be taken. The jEdit context menu provides
  1463   various actions, as far as applicable:
  1465   \<^medskip>
  1466   \begin{tabular}{l}
  1467   @{action_ref "isabelle.complete-word"} \\
  1468   @{action_ref "isabelle.exclude-word"} \\
  1469   @{action_ref "isabelle.exclude-word-permanently"} \\
  1470   @{action_ref "isabelle.include-word"} \\
  1471   @{action_ref "isabelle.include-word-permanently"} \\
  1472   \end{tabular}
  1473   \<^medskip>
  1475   Instead of the specific @{action_ref "isabelle.complete-word"}, it is also
  1476   possible to use the generic @{action_ref "isabelle.complete"} with its
  1477   default keyboard shortcut \<^verbatim>\<open>C+b\<close>.
  1479   \<^medskip>
  1480   Dictionary lookup uses some educated guesses about lower-case, upper-case,
  1481   and capitalized words. This is oriented on common use in English, where this
  1482   aspect is not decisive for proper spelling (in contrast to German, for
  1483   example).
  1484 \<close>
  1487 subsection \<open>Semantic completion context \label{sec:completion-context}\<close>
  1489 text \<open>
  1490   Completion depends on a semantic context that is provided by the prover,
  1491   although with some delay, because at least a full PIDE protocol round-trip
  1492   is required. Until that information becomes available in the PIDE
  1493   document-model, the default context is given by the outer syntax of the
  1494   editor mode (see also \secref{sec:buffer-node}).
  1496   The semantic \<^emph>\<open>language context\<close> provides information about nested
  1497   sub-languages of Isabelle: keywords are only completed for outer syntax, and
  1498   antiquotations for languages that support them. Symbol abbreviations only
  1499   work for specific sub-languages: e.g.\ ``\<^verbatim>\<open>=>\<close>'' is \<^emph>\<open>not\<close> completed in
  1500   regular ML source, but is completed within ML strings, comments,
  1501   antiquotations. Backslash representations of symbols like ``\<^verbatim>\<open>\foobar\<close>'' or
  1502   ``\<^verbatim>\<open>\<foobar>\<close>'' work in any context --- after additional confirmation.
  1504   The prover may produce \<^emph>\<open>no completion\<close> markup in exceptional situations, to
  1505   tell that some language keywords should be excluded from further completion
  1506   attempts. For example, ``\<^verbatim>\<open>:\<close>'' within accepted Isar syntax looses its
  1507   meaning as abbreviation for symbol ``\<open>\<in>\<close>''.
  1508 \<close>
  1511 subsection \<open>Input events \label{sec:completion-input}\<close>
  1513 text \<open>
  1514   Completion is triggered by certain events produced by the user, with
  1515   optional delay after keyboard input according to @{system_option
  1516   jedit_completion_delay}.
  1518   \<^descr>[Explicit completion] works via action @{action_ref "isabelle.complete"}
  1519   with keyboard shortcut \<^verbatim>\<open>C+b\<close>. This overrides the shortcut for @{action_ref
  1520   "complete-word"} in jEdit, but it is possible to restore the original jEdit
  1521   keyboard mapping of @{action "complete-word"} via \<^emph>\<open>Global Options~/
  1522   Shortcuts\<close> and invent a different one for @{action "isabelle.complete"}.
  1524   \<^descr>[Explicit spell-checker completion] works via @{action_ref
  1525   "isabelle.complete-word"}, which is exposed in the jEdit context menu, if
  1526   the mouse points to a word that the spell-checker can complete.
  1528   \<^descr>[Implicit completion] works via regular keyboard input of the editor. It
  1529   depends on further side-conditions:
  1531     \<^enum> The system option @{system_option_ref jedit_completion} needs to be
  1532     enabled (default).
  1534     \<^enum> Completion of syntax keywords requires at least 3 relevant characters in
  1535     the text.
  1537     \<^enum> The system option @{system_option_ref jedit_completion_delay} determines
  1538     an additional delay (0.5 by default), before opening a completion popup.
  1539     The delay gives the prover a chance to provide semantic completion
  1540     information, notably the context (\secref{sec:completion-context}).
  1542     \<^enum> The system option @{system_option_ref jedit_completion_immediate}
  1543     (enabled by default) controls whether replacement text should be inserted
  1544     immediately without popup, regardless of @{system_option
  1545     jedit_completion_delay}. This aggressive mode of completion is restricted
  1546     to symbol abbreviations that are not plain words (\secref{sec:symbols}).
  1548     \<^enum> Completion of symbol abbreviations with only one relevant character in
  1549     the text always enforces an explicit popup, regardless of
  1550     @{system_option_ref jedit_completion_immediate}.
  1551 \<close>
  1554 subsection \<open>Completion popup \label{sec:completion-popup}\<close>
  1556 text \<open>
  1557   A \<^emph>\<open>completion popup\<close> is a minimally invasive GUI component over the text
  1558   area that offers a selection of completion items to be inserted into the
  1559   text, e.g.\ by mouse clicks. Items are sorted dynamically, according to the
  1560   frequency of selection, with persistent history. The popup may interpret
  1561   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>,
  1562   \<^verbatim>\<open>PAGE_DOWN\<close>, but all other key events are passed to the underlying text
  1563   area. This allows to ignore unwanted completions most of the time and
  1564   continue typing quickly. Thus the popup serves as a mechanism of
  1565   confirmation of proposed items, while the default is to continue without
  1566   completion.
  1568   The meaning of special keys is as follows:
  1570   \<^medskip>
  1571   \begin{tabular}{ll}
  1572   \<^bold>\<open>key\<close> & \<^bold>\<open>action\<close> \\\hline
  1573   \<^verbatim>\<open>ENTER\<close> & select completion (if @{system_option jedit_completion_select_enter}) \\
  1574   \<^verbatim>\<open>TAB\<close> & select completion (if @{system_option jedit_completion_select_tab}) \\
  1575   \<^verbatim>\<open>ESCAPE\<close> & dismiss popup \\
  1576   \<^verbatim>\<open>UP\<close> & move up one item \\
  1577   \<^verbatim>\<open>DOWN\<close> & move down one item \\
  1578   \<^verbatim>\<open>PAGE_UP\<close> & move up one page of items \\
  1579   \<^verbatim>\<open>PAGE_DOWN\<close> & move down one page of items \\
  1580   \end{tabular}
  1581   \<^medskip>
  1583   Movement within the popup is only active for multiple items. Otherwise the
  1584   corresponding key event retains its standard meaning within the underlying
  1585   text area.
  1586 \<close>
  1589 subsection \<open>Insertion \label{sec:completion-insert}\<close>
  1591 text \<open>
  1592   Completion may first propose replacements to be selected (via a popup), or
  1593   replace text immediately in certain situations and depending on certain
  1594   options like @{system_option jedit_completion_immediate}. In any case,
  1595   insertion works uniformly, by imitating normal jEdit text insertion,
  1596   depending on the state of the \<^emph>\<open>text selection\<close>. Isabelle/jEdit tries to
  1597   accommodate the most common forms of advanced selections in jEdit, but not
  1598   all combinations make sense. At least the following important cases are
  1599   well-defined:
  1601     \<^descr>[No selection.] The original is removed and the replacement inserted,
  1602     depending on the caret position.
  1604     \<^descr>[Rectangular selection of zero width.] This special case is treated by
  1605     jEdit as ``tall caret'' and insertion of completion imitates its normal
  1606     behaviour: separate copies of the replacement are inserted for each line
  1607     of the selection.
  1609     \<^descr>[Other rectangular selection or multiple selections.] Here the original
  1610     is removed and the replacement is inserted for each line (or segment) of
  1611     the selection.
  1613   Support for multiple selections is particularly useful for \<^emph>\<open>HyperSearch\<close>:
  1614   clicking on one of the items in the \<^emph>\<open>HyperSearch Results\<close> window makes
  1615   jEdit select all its occurrences in the corresponding line of text. Then
  1616   explicit completion can be invoked via \<^verbatim>\<open>C+b\<close>, e.g.\ to replace occurrences
  1617   of \<^verbatim>\<open>-->\<close> by \<open>\<longrightarrow>\<close>.
  1619   \<^medskip>
  1620   Insertion works by removing and inserting pieces of text from the buffer.
  1621   This counts as one atomic operation on the jEdit history. Thus unintended
  1622   completions may be reverted by the regular @{action undo} action of jEdit.
  1623   According to normal jEdit policies, the recovered text after @{action undo}
  1624   is selected: \<^verbatim>\<open>ESCAPE\<close> is required to reset the selection and to continue
  1625   typing more text.
  1626 \<close>
  1629 subsection \<open>Options \label{sec:completion-options}\<close>
  1631 text \<open>
  1632   This is a summary of Isabelle/Scala system options that are relevant for
  1633   completion. They may be configured in \<^emph>\<open>Plugin Options~/ Isabelle~/ General\<close>
  1634   as usual.
  1636   \<^item> @{system_option_def completion_limit} specifies the maximum number of
  1637   items for various semantic completion operations (name-space entries etc.)
  1639   \<^item> @{system_option_def jedit_completion} guards implicit completion via
  1640   regular jEdit key events (\secref{sec:completion-input}): it allows to
  1641   disable implicit completion altogether.
  1643   \<^item> @{system_option_def jedit_completion_select_enter} and @{system_option_def
  1644   jedit_completion_select_tab} enable keys to select a completion item from
  1645   the popup (\secref{sec:completion-popup}). Note that a regular mouse click
  1646   on the list of items is always possible.
  1648   \<^item> @{system_option_def jedit_completion_context} specifies whether the
  1649   language context provided by the prover should be used at all. Disabling
  1650   that option makes completion less ``semantic''. Note that incomplete or
  1651   severely broken input may cause some disagreement of the prover and the user
  1652   about the intended language context.
  1654   \<^item> @{system_option_def jedit_completion_delay} and @{system_option_def
  1655   jedit_completion_immediate} determine the handling of keyboard events for
  1656   implicit completion (\secref{sec:completion-input}).
  1658   A @{system_option jedit_completion_delay}~\<^verbatim>\<open>> 0\<close> postpones the processing of
  1659   key events, until after the user has stopped typing for the given time span,
  1660   but @{system_option jedit_completion_immediate}~\<^verbatim>\<open>= true\<close> means that
  1661   abbreviations of Isabelle symbols are handled nonetheless.
  1663   \<^item> @{system_option_def completion_path_ignore} specifies ``glob''
  1664   patterns to ignore in file-system path completion (separated by colons),
  1665   e.g.\ backup files ending with tilde.
  1667   \<^item> @{system_option_def spell_checker} is a global guard for all spell-checker
  1668   operations: it allows to disable that mechanism altogether.
  1670   \<^item> @{system_option_def spell_checker_dictionary} determines the current
  1671   dictionary, taken from the colon-separated list in the settings variable
  1672   @{setting_def JORTHO_DICTIONARIES}. There are jEdit actions to specify local
  1673   updates to a dictionary, by including or excluding words. The result of
  1674   permanent dictionary updates is stored in the directory \<^path>\<open>$ISABELLE_HOME_USER/dictionaries\<close>, in a separate file for each dictionary.
  1676   \<^item> @{system_option_def spell_checker_include} specifies a comma-separated
  1677   list of markup elements that delimit words in the source that is subject to
  1678   spell-checking, including various forms of comments.
  1680   \<^item> @{system_option_def spell_checker_exclude} specifies a comma-separated
  1681   list of markup elements that disable spell-checking (e.g.\ in nested
  1682   antiquotations).
  1683 \<close>
  1686 section \<open>Automatically tried tools \label{sec:auto-tools}\<close>
  1688 text \<open>
  1689   Continuous document processing works asynchronously in the background.
  1690   Visible document source that has been evaluated may get augmented by
  1691   additional results of \<^emph>\<open>asynchronous print functions\<close>. An example for that
  1692   is proof state output, if that is enabled in the Output panel
  1693   (\secref{sec:output}). More heavy-weight print functions may be applied as
  1694   well, e.g.\ to prove or disprove parts of the formal text by other means.
  1696   Isabelle/HOL provides various automatically tried tools that operate on
  1697   outermost goal statements (e.g.\ @{command lemma}, @{command theorem}),
  1698   independently of the state of the current proof attempt. They work
  1699   implicitly without any arguments. Results are output as \<^emph>\<open>information
  1700   messages\<close>, which are indicated in the text area by blue squiggles and a blue
  1701   information sign in the gutter (see \figref{fig:auto-tools}). The message
  1702   content may be shown as for other output (see also \secref{sec:output}).
  1703   Some tools produce output with \<^emph>\<open>sendback\<close> markup, which means that clicking
  1704   on certain parts of the text inserts that into the source in the proper
  1705   place.
  1707   \begin{figure}[!htb]
  1708   \begin{center}
  1709   \includegraphics[scale=0.333]{auto-tools}
  1710   \end{center}
  1711   \caption{Result of automatically tried tools}
  1712   \label{fig:auto-tools}
  1713   \end{figure}
  1715   \<^medskip>
  1716   The following Isabelle system options control the behavior of automatically
  1717   tried tools (see also the jEdit dialog window \<^emph>\<open>Plugin Options~/ Isabelle~/
  1718   General~/ Automatically tried tools\<close>):
  1720   \<^item> @{system_option_ref auto_methods} controls automatic use of a combination
  1721   of standard proof methods (@{method auto}, @{method simp}, @{method blast},
  1722   etc.). This corresponds to the Isar command @{command_ref "try0"} @{cite
  1723   "isabelle-isar-ref"}.
  1725   The tool is disabled by default, since unparameterized invocation of
  1726   standard proof methods often consumes substantial CPU resources without
  1727   leading to success.
  1729   \<^item> @{system_option_ref auto_nitpick} controls a slightly reduced version of
  1730   @{command_ref nitpick}, which tests for counterexamples using first-order
  1731   relational logic. See also the Nitpick manual @{cite "isabelle-nitpick"}.
  1733   This tool is disabled by default, due to the extra overhead of invoking an
  1734   external Java process for each attempt to disprove a subgoal.
  1736   \<^item> @{system_option_ref auto_quickcheck} controls automatic use of
  1737   @{command_ref quickcheck}, which tests for counterexamples using a series of
  1738   assignments for free variables of a subgoal.
  1740   This tool is \<^emph>\<open>enabled\<close> by default. It requires little overhead, but is a
  1741   bit weaker than @{command nitpick}.
  1743   \<^item> @{system_option_ref auto_sledgehammer} controls a significantly reduced
  1744   version of @{command_ref sledgehammer}, which attempts to prove a subgoal
  1745   using external automatic provers. See also the Sledgehammer manual @{cite
  1746   "isabelle-sledgehammer"}.
  1748   This tool is disabled by default, due to the relatively heavy nature of
  1749   Sledgehammer.
  1751   \<^item> @{system_option_ref auto_solve_direct} controls automatic use of
  1752   @{command_ref solve_direct}, which checks whether the current subgoals can
  1753   be solved directly by an existing theorem. This also helps to detect
  1754   duplicate lemmas.
  1756   This tool is \<^emph>\<open>enabled\<close> by default.
  1759   Invocation of automatically tried tools is subject to some global policies
  1760   of parallel execution, which may be configured as follows:
  1762   \<^item> @{system_option_ref auto_time_limit} (default 2.0) determines the timeout
  1763   (in seconds) for each tool execution.
  1765   \<^item> @{system_option_ref auto_time_start} (default 1.0) determines the start
  1766   delay (in seconds) for automatically tried tools, after the main command
  1767   evaluation is finished.
  1770   Each tool is submitted independently to the pool of parallel execution tasks
  1771   in Isabelle/ML, using hardwired priorities according to its relative
  1772   ``heaviness''. The main stages of evaluation and printing of proof states
  1773   take precedence, but an already running tool is not canceled and may thus
  1774   reduce reactivity of proof document processing.
  1776   Users should experiment how the available CPU resources (number of cores)
  1777   are best invested to get additional feedback from prover in the background,
  1778   by using a selection of weaker or stronger tools.
  1779 \<close>
  1782 section \<open>Sledgehammer \label{sec:sledgehammer}\<close>
  1784 text \<open>
  1785   The \<^emph>\<open>Sledgehammer\<close> panel (\figref{fig:sledgehammer}) provides a view on
  1786   some independent execution of the Isar command @{command_ref sledgehammer},
  1787   with process indicator (spinning wheel) and GUI elements for important
  1788   Sledgehammer arguments and options. Any number of Sledgehammer panels may be
  1789   active, according to the standard policies of Dockable Window Management in
  1790   jEdit. Closing such windows also cancels the corresponding prover tasks.
  1792   \begin{figure}[!htb]
  1793   \begin{center}
  1794   \includegraphics[scale=0.333]{sledgehammer}
  1795   \end{center}
  1796   \caption{An instance of the Sledgehammer panel}
  1797   \label{fig:sledgehammer}
  1798   \end{figure}
  1800   The \<^emph>\<open>Apply\<close> button attaches a fresh invocation of @{command sledgehammer}
  1801   to the command where the cursor is pointing in the text --- this should be
  1802   some pending proof problem. Further buttons like \<^emph>\<open>Cancel\<close> and \<^emph>\<open>Locate\<close>
  1803   help to manage the running process.
  1805   Results appear incrementally in the output window of the panel. Proposed
  1806   proof snippets are marked-up as \<^emph>\<open>sendback\<close>, which means a single mouse
  1807   click inserts the text into a suitable place of the original source. Some
  1808   manual editing may be required nonetheless, say to remove earlier proof
  1809   attempts.
  1810 \<close>
  1813 chapter \<open>Isabelle document preparation\<close>
  1815 text \<open>
  1816   The ultimate purpose of Isabelle is to produce nicely rendered documents
  1817   with the Isabelle document preparation system, which is based on {\LaTeX};
  1818   see also @{cite "isabelle-system" and "isabelle-isar-ref"}. Isabelle/jEdit
  1819   provides some additional support for document editing.
  1820 \<close>
  1823 section \<open>Document outline\<close>
  1825 text \<open>
  1826   Theory sources may contain document markup commands, such as @{command_ref
  1827   chapter}, @{command_ref section}, @{command subsection}. The Isabelle
  1828   SideKick parser (\secref{sec:sidekick}) represents this document outline as
  1829   structured tree view, with formal statements and proofs nested inside; see
  1830   \figref{fig:sidekick-document}.
  1832   \begin{figure}[!htb]
  1833   \begin{center}
  1834   \includegraphics[scale=0.333]{sidekick-document}
  1835   \end{center}
  1836   \caption{Isabelle document outline via SideKick tree view}
  1837   \label{fig:sidekick-document}
  1838   \end{figure}
  1840   It is also possible to use text folding according to this structure, by
  1841   adjusting \<^emph>\<open>Utilities / Buffer Options / Folding mode\<close> of jEdit. The default
  1842   mode \<^verbatim>\<open>isabelle\<close> uses the structure of formal definitions, statements, and
  1843   proofs. The alternative mode \<^verbatim>\<open>sidekick\<close> uses the document structure of the
  1844   SideKick parser, as explained above.
  1845 \<close>
  1848 section \<open>Markdown structure\<close>
  1850 text \<open>
  1851   Document text is internally structured in paragraphs and nested lists, using
  1852   notation that is similar to Markdown\<^footnote>\<open>\<^url>\<open>\<close>\<close>. There are
  1853   special control symbols for items of different kinds of lists, corresponding
  1854   to \<^verbatim>\<open>itemize\<close>, \<^verbatim>\<open>enumerate\<close>, \<^verbatim>\<open>description\<close> in {\LaTeX}. This is illustrated
  1855   in for \<^verbatim>\<open>itemize\<close> in \figref{fig:markdown-document}.
  1857   \begin{figure}[!htb]
  1858   \begin{center}
  1859   \includegraphics[scale=0.333]{markdown-document}
  1860   \end{center}
  1861   \caption{Markdown structure within document text}
  1862   \label{fig:markdown-document}
  1863   \end{figure}
  1865   Items take colour according to the depth of nested lists. This helps to
  1866   explore the implicit rules for list structure interactively. There is also
  1867   markup for individual paragraphs in the text: it may be explored via mouse
  1868   hovering with \<^verbatim>\<open>CONTROL\<close> / \<^verbatim>\<open>COMMAND\<close> as usual
  1869   (\secref{sec:tooltips-hyperlinks}).
  1870 \<close>
  1873 section \<open>Citations and Bib{\TeX} entries \label{sec:bibtex}\<close>
  1875 text \<open>
  1876   Citations are managed by {\LaTeX} and Bib{\TeX} in \<^verbatim>\<open>.bib\<close> files. The
  1877   Isabelle session build process and the @{tool latex} tool @{cite
  1878   "isabelle-system"} are smart enough to assemble the result, based on the
  1879   session directory layout.
  1881   The document antiquotation \<open>@{cite}\<close> is described in @{cite
  1882   "isabelle-isar-ref"}. Within the Prover IDE it provides semantic markup for
  1883   tooltips, hyperlinks, and completion for Bib{\TeX} database entries.
  1884   Isabelle/jEdit does \<^emph>\<open>not\<close> know about the actual Bib{\TeX} environment used
  1885   in {\LaTeX} batch-mode, but it can take citations from those \<^verbatim>\<open>.bib\<close> files
  1886   that happen to be open in the editor; see \figref{fig:cite-completion}.
  1888   \begin{figure}[!htb]
  1889   \begin{center}
  1890   \includegraphics[scale=0.333]{cite-completion}
  1891   \end{center}
  1892   \caption{Semantic completion of citations from open Bib{\TeX} files}
  1893   \label{fig:cite-completion}
  1894   \end{figure}
  1896   Isabelle/jEdit also provides IDE support for editing \<^verbatim>\<open>.bib\<close> files
  1897   themselves. There is syntax highlighting based on entry types (according to
  1898   standard Bib{\TeX} styles), a context-menu to compose entries
  1899   systematically, and a SideKick tree view of the overall content; see
  1900   \figref{fig:bibtex-mode}. Semantic checking with errors and warnings is
  1901   performed by the original \<^verbatim>\<open>bibtex\<close> tool using style \<^verbatim>\<open>plain\<close>: different
  1902   Bib{\TeX} styles may produce slightly different results.
  1904   \begin{figure}[!htb]
  1905   \begin{center}
  1906   \includegraphics[scale=0.333]{bibtex-mode}
  1907   \end{center}
  1908   \caption{Bib{\TeX} mode with context menu, SideKick tree view, and
  1909     semantic output from the \<^verbatim>\<open>bibtex\<close> tool}
  1910   \label{fig:bibtex-mode}
  1911   \end{figure}
  1913   Regular document preview (\secref{sec:document-preview}) of \<^verbatim>\<open>.bib\<close> files
  1914   approximates the usual {\LaTeX} bibliography output in HTML (using style
  1915   \<^verbatim>\<open>unsort\<close>).
  1916 \<close>
  1919 section \<open>Document preview \label{sec:document-preview}\<close>
  1921 text \<open>
  1922   The action @{action_def isabelle.preview} opens an HTML preview of the
  1923   current document node in the default web browser. The content is derived
  1924   from the semantic markup produced by the prover, and thus depends on the
  1925   status of formal processing.
  1927   Action @{action_def isabelle.draft} is similar to @{action
  1928   isabelle.preview}, but shows a plain-text document draft.
  1929 \<close>
  1932 chapter \<open>ML debugging within the Prover IDE\<close>
  1934 text \<open>
  1935   Isabelle/ML is based on Poly/ML\<^footnote>\<open>\<^url>\<open>\<close>\<close> and thus
  1936   benefits from the source-level debugger of that implementation of Standard
  1937   ML. The Prover IDE provides the \<^emph>\<open>Debugger\<close> dockable to connect to running
  1938   ML threads, inspect the stack frame with local ML bindings, and evaluate ML
  1939   expressions in a particular run-time context. A typical debugger session is
  1940   shown in \figref{fig:ml-debugger}.
  1942   ML debugging depends on the following pre-requisites.
  1944     \<^enum> ML source needs to be compiled with debugging enabled. This may be
  1945     controlled for particular chunks of ML sources using any of the subsequent
  1946     facilities.
  1948       \<^enum> The system option @{system_option_ref ML_debugger} as implicit state
  1949       of the Isabelle process. It may be changed in the menu \<^emph>\<open>Plugins /
  1950       Plugin Options / Isabelle / General\<close>. ML modules need to be reloaded and
  1951       recompiled to pick up that option as intended.
  1953       \<^enum> The configuration option @{attribute_ref ML_debugger}, with an
  1954       attribute of the same name, to update a global or local context (e.g.\
  1955       with the @{command declare} command).
  1957       \<^enum> Commands that modify @{attribute ML_debugger} state for individual
  1958       files: @{command_ref ML_file_debug}, @{command_ref ML_file_no_debug},
  1959       @{command_ref SML_file_debug}, @{command_ref SML_file_no_debug}.
  1961     The instrumentation of ML code for debugging causes minor run-time
  1962     overhead. ML modules that implement critical system infrastructure may
  1963     lead to deadlocks or other undefined behaviour, when put under debugger
  1964     control!
  1966     \<^enum> The \<^emph>\<open>Debugger\<close> panel needs to be active, otherwise the program ignores
  1967     debugger instrumentation of the compiler and runs unmanaged. It is also
  1968     possible to start debugging with the panel open, and later undock it, to
  1969     let the program continue unhindered.
  1971     \<^enum> The ML program needs to be stopped at a suitable breakpoint, which may
  1972     be activated individually or globally as follows.
  1974     For ML sources that have been compiled with debugger support, the IDE
  1975     visualizes possible breakpoints in the text. A breakpoint may be toggled
  1976     by pointing accurately with the mouse, with a right-click to activate
  1977     jEdit's context menu and its \<^emph>\<open>Toggle Breakpoint\<close> item. Alternatively, the
  1978     \<^emph>\<open>Break\<close> checkbox in the \<^emph>\<open>Debugger\<close> panel may be enabled to stop ML
  1979     threads always at the next possible breakpoint.
  1981   Note that the state of individual breakpoints \<^emph>\<open>gets lost\<close> when the
  1982   coresponding ML source is re-compiled! This may happen unintentionally,
  1983   e.g.\ when following hyperlinks into ML modules that have not been loaded
  1984   into the IDE before.
  1986   \begin{figure}[!htb]
  1987   \begin{center}
  1988   \includegraphics[scale=0.333]{ml-debugger}
  1989   \end{center}
  1990   \caption{ML debugger session}
  1991   \label{fig:ml-debugger}
  1992   \end{figure}
  1994   The debugger panel (\figref{fig:ml-debugger}) shows a list of all threads
  1995   that are presently stopped. Each thread shows a stack of all function
  1996   invocations that lead to the current breakpoint at the top.
  1998   It is possible to jump between stack positions freely, by clicking on this
  1999   list. The current situation is displayed in the big output window, as a
  2000   local ML environment with names and printed values.
  2002   ML expressions may be evaluated in the current context by entering snippets
  2003   of source into the text fields labeled \<open>Context\<close> and \<open>ML\<close>, and pushing the
  2004   \<open>Eval\<close> button. By default, the source is interpreted as Isabelle/ML with the
  2005   usual support for antiquotations (like @{command ML}, @{command ML_file}).
  2006   Alternatively, strict Standard ML may be enforced via the \<^emph>\<open>SML\<close> checkbox
  2007   (like @{command SML_file}).
  2009   The context for Isabelle/ML is optional, it may evaluate to a value of type
  2010   \<^ML_type>\<open>theory\<close>, \<^ML_type>\<open>Proof.context\<close>, or \<^ML_type>\<open>Context.generic\<close>.
  2011   Thus the given ML expression (with its antiquotations) may be subject to the
  2012   intended dynamic run-time context, instead of the static compile-time
  2013   context.
  2015   \<^medskip>
  2016   The buttons labeled \<^emph>\<open>Continue\<close>, \<^emph>\<open>Step\<close>, \<^emph>\<open>Step over\<close>, \<^emph>\<open>Step out\<close>
  2017   recommence execution of the program, with different policies concerning
  2018   nested function invocations. The debugger always moves the cursor within the
  2019   ML source to the next breakpoint position, and offers new stack frames as
  2020   before.
  2021 \<close>
  2024 chapter \<open>Miscellaneous tools\<close>
  2026 section \<open>Timing\<close>
  2028 text \<open>
  2029   Managed evaluation of commands within PIDE documents includes timing
  2030   information, which consists of elapsed (wall-clock) time, CPU time, and GC
  2031   (garbage collection) time. Note that in a multithreaded system it is
  2032   difficult to measure execution time precisely: elapsed time is closer to the
  2033   real requirements of runtime resources than CPU or GC time, which are both
  2034   subject to influences from the parallel environment that are outside the
  2035   scope of the current command transaction.
  2037   The \<^emph>\<open>Timing\<close> panel provides an overview of cumulative command timings for
  2038   each document node. Commands with elapsed time below the given threshold are
  2039   ignored in the grand total. Nodes are sorted according to their overall
  2040   timing. For the document node that corresponds to the current buffer,
  2041   individual command timings are shown as well. A double-click on a theory
  2042   node or command moves the editor focus to that particular source position.
  2044   It is also possible to reveal individual timing information via some tooltip
  2045   for the corresponding command keyword, using the technique of mouse hovering
  2046   with \<^verbatim>\<open>CONTROL\<close>~/ \<^verbatim>\<open>COMMAND\<close> modifier (\secref{sec:tooltips-hyperlinks}).
  2047   Actual display of timing depends on the global option @{system_option_ref
  2048   jedit_timing_threshold}, which can be configured in \<^emph>\<open>Plugin Options~/
  2049   Isabelle~/ General\<close>.
  2051   \<^medskip>
  2052   The \<^emph>\<open>Monitor\<close> panel visualizes various data collections about recent
  2053   activity of the Isabelle/ML task farm and the underlying ML runtime system.
  2054   The display is continuously updated according to @{system_option_ref
  2055   editor_chart_delay}. Note that the painting of the chart takes considerable
  2056   runtime itself --- on the Java Virtual Machine that runs Isabelle/Scala, not
  2057   Isabelle/ML. Internally, the Isabelle/Scala module \<^verbatim>\<open>isabelle.ML_Statistics\<close>
  2058   provides further access to statistics of Isabelle/ML.
  2059 \<close>
  2062 section \<open>Low-level output\<close>
  2064 text \<open>
  2065   Prover output is normally shown directly in the main text area or specific
  2066   panels like \<^emph>\<open>Output\<close> (\secref{sec:output}) or \<^emph>\<open>State\<close>
  2067   (\secref{sec:state-output}). Beyond this, it is occasionally useful to
  2068   inspect low-level output channels via some of the following additional
  2069   panels:
  2071   \<^item> \<^emph>\<open>Protocol\<close> shows internal messages between the Isabelle/Scala and
  2072   Isabelle/ML side of the PIDE document editing protocol. Recording of
  2073   messages starts with the first activation of the corresponding dockable
  2074   window; earlier messages are lost.
  2076   Actual display of protocol messages causes considerable slowdown, so it is
  2077   important to undock all \<^emph>\<open>Protocol\<close> panels for production work.
  2079   \<^item> \<^emph>\<open>Raw Output\<close> shows chunks of text from the \<^verbatim>\<open>stdout\<close> and \<^verbatim>\<open>stderr\<close>
  2080   channels of the prover process. Recording of output starts with the first
  2081   activation of the corresponding dockable window; earlier output is lost.
  2083   The implicit stateful nature of physical I/O channels makes it difficult to
  2084   relate raw output to the actual command from where it was originating.
  2085   Parallel execution may add to the confusion. Peeking at physical process I/O
  2086   is only the last resort to diagnose problems with tools that are not PIDE
  2087   compliant.
  2089   Under normal circumstances, prover output always works via managed message
  2090   channels (corresponding to \<^ML>\<open>writeln\<close>, \<^ML>\<open>warning\<close>, \<^ML>\<open>Output.error_message\<close> in Isabelle/ML), which are displayed by regular means
  2091   within the document model (\secref{sec:output}). Unhandled Isabelle/ML
  2092   exceptions are printed by the system via \<^ML>\<open>Output.error_message\<close>.
  2094   \<^item> \<^emph>\<open>Syslog\<close> shows system messages that might be relevant to diagnose
  2095   problems with the startup or shutdown phase of the prover process; this also
  2096   includes raw output on \<^verbatim>\<open>stderr\<close>. Isabelle/ML also provides an explicit \<^ML>\<open>Output.system_message\<close> operation, which is occasionally useful for
  2097   diagnostic purposes within the system infrastructure itself.
  2099   A limited amount of syslog messages are buffered, independently of the
  2100   docking state of the \<^emph>\<open>Syslog\<close> panel. This allows to diagnose serious
  2101   problems with Isabelle/PIDE process management, outside of the actual
  2102   protocol layer.
  2104   Under normal situations, such low-level system output can be ignored.
  2105 \<close>
  2108 chapter \<open>Known problems and workarounds \label{sec:problems}\<close>
  2110 text \<open>
  2111   \<^item> \<^bold>\<open>Problem:\<close> Odd behavior of some diagnostic commands with global
  2112   side-effects, like writing a physical file.
  2114   \<^bold>\<open>Workaround:\<close> Copy/paste complete command text from elsewhere, or disable
  2115   continuous checking temporarily.
  2117   \<^item> \<^bold>\<open>Problem:\<close> Keyboard shortcuts \<^verbatim>\<open>C+PLUS\<close> and \<^verbatim>\<open>C+MINUS\<close> for adjusting the
  2118   editor font size depend on platform details and national keyboards.
  2120   \<^bold>\<open>Workaround:\<close> Rebind keys via \<^emph>\<open>Global Options~/ Shortcuts\<close>.
  2122   \<^item> \<^bold>\<open>Problem:\<close> The Mac OS X key sequence \<^verbatim>\<open>COMMAND+COMMA\<close> for application
  2123   \<^emph>\<open>Preferences\<close> is in conflict with the jEdit default keyboard shortcut for
  2124   \<^emph>\<open>Incremental Search Bar\<close> (action @{action_ref "quick-search"}).
  2126   \<^bold>\<open>Workaround:\<close> Rebind key via \<^emph>\<open>Global Options~/ Shortcuts\<close> according to
  2127   national keyboard, e.g.\ \<^verbatim>\<open>COMMAND+SLASH\<close> on English ones.
  2129   \<^item> \<^bold>\<open>Problem:\<close> On Mac OS X with native Apple look-and-feel, some exotic
  2130   national keyboards may cause a conflict of menu accelerator keys with
  2131   regular jEdit key bindings. This leads to duplicate execution of the
  2132   corresponding jEdit action.
  2134   \<^bold>\<open>Workaround:\<close> Disable the native Apple menu bar via Java runtime option
  2135   \<^verbatim>\<open>-Dapple.laf.useScreenMenuBar=false\<close>.
  2137   \<^item> \<^bold>\<open>Problem:\<close> Mac OS X system fonts sometimes lead to character drop-outs in
  2138   the main text area.
  2140   \<^bold>\<open>Workaround:\<close> Use the default \<^verbatim>\<open>Isabelle DejaVu\<close> fonts.
  2142   \<^item> \<^bold>\<open>Problem:\<close> Some Linux/X11 input methods such as IBus tend to disrupt key
  2143   event handling of Java/AWT/Swing.
  2145   \<^bold>\<open>Workaround:\<close> Do not use X11 input methods. Note that environment variable
  2146   \<^verbatim>\<open>XMODIFIERS\<close> is reset by default within Isabelle settings.
  2148   \<^item> \<^bold>\<open>Problem:\<close> Some Linux/X11 window managers that are not ``re-parenting''
  2149   cause problems with additional windows opened by Java. This affects either
  2150   historic or neo-minimalistic window managers like \<^verbatim>\<open>awesome\<close> or \<^verbatim>\<open>xmonad\<close>.
  2152   \<^bold>\<open>Workaround:\<close> Use a regular re-parenting X11 window manager.
  2154   \<^item> \<^bold>\<open>Problem:\<close> Various forks of Linux/X11 window managers and desktop
  2155   environments (like Gnome) disrupt the handling of menu popups and mouse
  2156   positions of Java/AWT/Swing.
  2158   \<^bold>\<open>Workaround:\<close> Use suitable version of Linux desktops.
  2160   \<^item> \<^bold>\<open>Problem:\<close> Full-screen mode via jEdit action @{action_ref
  2161   "toggle-full-screen"} (default keyboard shortcut \<^verbatim>\<open>F11\<close>) works on Windows,
  2162   but not on Mac OS X or various Linux/X11 window managers.
  2164   \<^bold>\<open>Workaround:\<close> Use native full-screen control of the window manager (notably
  2165   on Mac OS X).
  2167   \<^item> \<^bold>\<open>Problem:\<close> Heap space of the JVM may fill up and render the Prover IDE
  2168   unresponsive, e.g.\ when editing big Isabelle sessions with many theories.
  2170   \<^bold>\<open>Workaround:\<close> Increase JVM heap parameters by editing platform-specific
  2171   files (for ``properties'' or ``options'') that are associated with the main
  2172   app bundle.
  2174   Also note that jEdit provides a heap space monitor in the status line
  2175   (bottom-right). Double-clicking on that causes full garbage-collection,
  2176   which sometimes helps in low-memory situations.
  2177 \<close>
  2179 end