Rearrange handbook files and merge developer handbook and user manual

build.gradle

@@ -85,7 +85,7 @@ asciidoctor {
 
     options doctype: 'book'
 
-    backends = ['html5', 'pdf']
+    backends = ['html5']
 
     attributes = [
         'source-highlighter': 'coderay',

config.yaml

 ---
-file: prob_developer.adoc
-title: ProB Developer Handbook
+file: prob_handbook.adoc
+title: ProB Handbook
 authors:
   - Jens Bendisposto
   - Joy Clark
   - Michael Leuschel
-content:
-  - developer
-  - appendix
----
-file: prob_user_manual.adoc
-title: ProB User Manual
-authors:
-  - Jens Bendisposto
-  - Michael Leuschel
 content:
   - user
   - model_examples

src/docs/chapter/user/01_The_ProB_Animator_and_Model_Checker.adoc

+
 [[the-prob-animator-and-modelchecker]]
+= The ProB Animator and Modelchecker
 
 [width="100%",cols="60%,40%",]
 |=======================================================================

src/docs/chapter/user/10_General/00_General.adoc → src/docs/chapter/user/10_General/00_section_header.adoc

+
 [[general]]
 = General
+:leveloffset: +1

src/docs/chapter/user/10_General/01_Installation.adoc

+
 [[installation]]
-== Installation
+= Installation
 
 [[what-are-the-available-versions]]
-=== What are the available versions?
+== What are the available versions?
 
 * The standalone Tcl/Tk Version of ProB (ProB Tcl/Tk)
 * The standalone command-line version of ProB
@@ -31,7 +32,7 @@ We are also developing a new Java-based API called
 command-line version and <<using-the-command-line-version-of-prob, here>> is how to use it.
 
 [[which-version-should-i-use]]
-=== Which version should I use?
+== Which version should I use?
 
 The standalone version Tcl/Tk of ProB contains a richer set of features
 than the Rodin version and also works on other formalisms than Event-B
@@ -43,7 +44,7 @@ ProB. Use the probcli version if you want to write batch scripts or
 prefer working from the command-line.
 
 [[installation-instruction-for-prob-standalone]]
-=== Installation Instruction for ProB (Standalone)
+== Installation Instruction for ProB (Standalone)
 
 NOTE: We have specific <<windows-installation-instructions, Windows installation instructions>>.
 These here are the generic instructions.
@@ -92,7 +93,7 @@ animate them. Have a look at the supplied Machines in the examples
 directory. Have fun! Please report bugs!
 
 [[checklisttroubleshooting]]
-==== Checklist/Troubleshooting
+=== Checklist/Troubleshooting
 
 * Java: be sure to have Java 7 or newer installed. Otherwise you will
 not be able to parse your own classical B machines as our parser is
@@ -115,6 +116,6 @@ dot viewer. See more information about the
 <<graphical-viewer,Graphical Viewer here>>.
 
 [[installation-instruction-for-prob-rodin-plugin]]
-=== Installation Instruction for ProB (Rodin Plugin)
+== Installation Instruction for ProB (Rodin Plugin)
 
 <<tutorial-rodin-first-step,This>> tutorial shows how to properly install ProB for Rodin.

src/docs/chapter/user/10_General/02_Windows_Installation_Instructions.adoc

+
 [[windows-specific-download-instructions]]
-== Windows Specific Download Instructions
+= Windows Specific Download Instructions
 
 [[go-to-the-prob-downloads-site]]
-=== Go to the ProB Downloads site
+== Go to the ProB Downloads site
 
 * Go to the page
 https://www3.hhu.de/stups/prob/index.php/Download[Download],
@@ -11,7 +12,7 @@ this should look as follows:
 image::ProBWindowsDownload.png[]
 
 [[install-tcltk-8.5]]
-=== Install Tcl/Tk 8.5
+== Install Tcl/Tk 8.5
 
 If Tcl/Tk 8.5 is already installed you can skip this step.
 
@@ -27,7 +28,7 @@ ProB.
 image::TkWindowsDownload.png[]
 
 [[install-java]]
-=== Install Java
+== Install Java
 
 If Java 7 or newer is already installed you can skip this step.
 
@@ -36,7 +37,7 @@ newer)] link provided in the `Dependencies` column and the `Windows` row above
 * Follow the installation instructions
 
 [[download-the-prob-for-windows-zipfile]]
-=== Download the ProB for Windows Zipfile
+== Download the ProB for Windows Zipfile
 
 * Click on the https://www3.hhu.de/stups/downloads/[Zipfile
 (with probcli)] link in the `Downloads` column and `Windows` row
@@ -51,20 +52,20 @@ The subfolder called `Microsoft.VC80.CRT` contains the DLLs for the
 Microsoft C runtime.
 
 [[optionally-download-graphviz]]
-=== Optionally Download GraphViz
+== Optionally Download GraphViz
 
 * Install the `dot` program and `dotty viewer` from
 http://www.graphviz.org/ or http://www.research.att.com/sw/tools/graphviz/[AT&T's Graphviz package]
 
 [[start-prob]]
-=== Start ProB
+== Start ProB
 
 * Start ProB by double-clicking on the ProBWin icon above
 * Try to open some of the examples provided in the Examples folder shown above
 * Contact us if you have problems
 
 [[checklist-troubleshooting]]
-=== Checklist/Troubleshooting
+== Checklist/Troubleshooting
 
 * Java: be sure to have Java 1.7 or newer installed. Otherwise you will
 not be able to parse your own classical B machines as our parser is

src/docs/chapter/user/10_General/10_Animation.adoc

+
 [[animation]]
-== Animation
+= Animation
 
 The animation facilities of ProB allow users to gain confidence in their
 specifications. These features try to be as user-friendly as possible
@@ -8,7 +9,7 @@ operation arguments or choice variables, and he uses the mouse to
 operate the animation).
 
 [[basic-animation]]
-=== Basic Animation
+== Basic Animation
 
 When the B specification is opened, the syntax and type checker analyses
 it and, if a syntax or type error is detected, it is then reported,
@@ -21,7 +22,7 @@ performed in the Enabled Operations pane. These operations can be of two
 types described below.
 
 [[operations-from-the-b-machine]]
-==== Operations from the B Machine
+=== Operations from the B Machine
 
 These operations are the ones whose preconditions and guards are
 satisfiable in the current state. The parameter values that make true
@@ -41,7 +42,7 @@ preconditions and guards.
 corresponds to a deadlock*
 
 [[virtual-operations]]
-==== Virtual Operations
+=== Virtual Operations
 
 There are three particular operations that correspond to specific tasks
 performed by ProB:
@@ -64,7 +65,7 @@ pane. These enable the user to explore interactively the behaviour of
 the B machine.
 
 [[animating-the-b-machine]]
-==== Animating the B machine
+=== Animating the B machine
 
 If the B machine has constants, one or several initialise constants
 operations are displayed. The user selects one of these operations, then
@@ -94,7 +95,7 @@ added to the History pane, the effect of the operation are computed and
 the state is updated in the State Properties pane.
 
 [[the-analyse-menu]]
-=== The Analyse menu
+== The Analyse menu
 
 At each point during the animation process, several useful commands
 displaying various information on the B machine are available in the
@@ -122,7 +123,7 @@ properties and the Analyse Assertions plays this role for the
 assertions.
 
 [[animation-preferences]]
-=== Animation Preferences
+== Animation Preferences
 
 The animation process in ProB can be configured via several preferences
 set in the preference window Preferences|Animation Preferences.
@@ -142,7 +143,7 @@ The preference Check invariant will toggle the display of the invariant
 status indicator in the State Properties pane.
 
 [[other-animation-features]]
-=== Other Animation Features
+== Other Animation Features
 
 Several other commands are provided by ProB in the _Animate_ menu for
 animating B specifications. The Reset command will set the state of the

src/docs/chapter/developer/Building_ProB_on_Windows.adoc → src/docs/chapter/user/10_General/Building_ProB_on_Windows.adoc

+
 [[building-prob-on-windows]]
 = Building ProB on Windows
 
-
 In case that you want to compile ProB from Source on Windows (XP),
 here are some information about the setup:
 

src/docs/chapter/user/10_General/Colours_of_enabled_operations.adoc

+
 [[colours-of-enabled-operations]]
-== Colours of enabled operations
+= Colours of enabled operations
 
 The enabled operations are shown in different colours, depending on the
 state where the operation leads to. If more than one rule of the

src/docs/chapter/user/10_General/Controlling_ProB_Preferences.adoc

+
 [[controlling-prob-preferences]]
-== Controlling ProB Preferences
+= Controlling ProB Preferences
 
 ProB provides a variety of preferences to control its behaviour. A list
 of the most important preferences can be found
@@ -8,7 +9,7 @@ page for probcli>>. We also have a separate <<deferred-sets,manual
 page about setting the sizes of deferred sets>>.
 
 [[setting-preferences-in-a-b-machine]]
-=== Setting Preferences in a B machine
+== Setting Preferences in a B machine
 
 This only works for classical B models. For a preference `P` you can add
 the following definition to the `DEFINITIONS` section of the main
@@ -19,7 +20,7 @@ machine:
 This will set the preference `P` to the value `VAL` for this model only.
 
 [[setting-preferences-from-the-command-line]]
-=== Setting Preferences from the command-line
+== Setting Preferences from the command-line
 
 You can set a preference `P` to a value `VAL` for a particular run of
 probcli by adding the command-line switch `-p P VAL`, e.g.,
@@ -44,7 +45,7 @@ set>> `GS` using the following command-line switch:
 `-card GS Val`
 
 [[setting-preferences-from-prob-tcltk]]
-=== Setting Preferences from ProB Tcl/Tk
+== Setting Preferences from ProB Tcl/Tk
 
 ProB Tcl/Tk stores your preferences settings in a file
 `ProB_Preferences.pl`.

src/docs/chapter/user/10_General/Current_Limitations.adoc

+
 [[current-limitations]]
-== Current Limitations
+= Current Limitations
 
 ProB in general requires all <<deferred-sets,deferred sets>> to be
 given a finite cardinality. If no cardinality is specified, a default
@@ -38,7 +39,7 @@ composition (or other uses of the semicolon).
 See the page <<using-prob-with-atelier-b,Using ProB with Atelier B>> for more details.
 
 [[multiple-machines-and-refinements]]
-=== Multiple Machines and Refinements
+== Multiple Machines and Refinements
 
 It is possible to use multiple B machines with ProB. However, ProB may
 not enforce all of the classical B visibility rules (although we try

src/docs/chapter/user/10_General/Deferred_Sets.adoc

+
 [[deferred-sets]]
-== Deferred Sets
+= Deferred Sets
 
 A deferred set in B is declared in the SETS Section and is not
 explicitly enumerated. In the example below, AA is a deferred set and BB
@@ -35,7 +36,7 @@ influence the size used for AA by ProB, for example:
 set the cardinality of AA to the constant.
 
 [[using-refinement-for-animation-preferences]]
-=== Using Refinement for Animation Preferences
+== Using Refinement for Animation Preferences
 
 Note: instead of adding AA = \{aa,bb} to the SETS clause you can also
 add `AA = {aa,bb} & aa/=bb` to the PROPERTIES clause. This can also be
@@ -52,7 +53,7 @@ END
 ....
 
 [[setting-deferred-set-cardinalities-within-probcli]]
-=== Setting Deferred Set Cardinalities within probcli
+== Setting Deferred Set Cardinalities within probcli
 
 From the command-line, using probcli you can use the command-line
 switch:

src/docs/chapter/user/10_General/Editors_for_ProB.adoc

+
 [[editors-for-prob]]
-== Editors for ProB
+= Editors for ProB
 
 [[prob-tcltk-editor]]
-=== ProB Tcl/Tk Editor
+== ProB Tcl/Tk Editor
 
 ProB Tcl/Tk contains an editor in which syntax errors are displayed and
 which can be used to edit B, CSP, Z and TLA+ models. The editor of
@@ -23,7 +24,7 @@ file with this editor. You can also use the command-key shortcut
 "Cmd-E" for this.
 
 [[launching-the-editor-in-probcli]]
-=== Launching the editor in probcli
+== Launching the editor in probcli
 
 The <<using-the-command-line-version-of-prob,probcli>> REPL
 (read-eval-print-loop) supports the command `:e` to open the current
@@ -36,10 +37,10 @@ In case errors occurred with the last command, this will also try and
 move the cursor to the corresponding location in the file.
 
 [[external-editors]]
-=== External Editors
+== External Editors
 
 [[vim]]
-==== VIM
+=== VIM
 
 A https://github.com/bivab/prob.vim[VIM plugin for ProB is available].
 It shows a quick fix list of parse and type errors for classical B
@@ -49,7 +50,7 @@ VIM has builtin syntax highlighting support for
 https://github.com/vim/vim/blob/master/runtime/syntax/b.vim[B].
 
 [[atom]]
-==== Atom
+=== Atom
 
 There is a package
 https://atom.io/packages/language-b-eventb[language-b-eventb] available
@@ -58,12 +59,12 @@ specification languages B and Event-B to Atom. It integrates with
 probcli to obtain error markers for syntax and type errors.
 
 [[bbedit]]
-==== BBEdit
+=== BBEdit
 
 Some https://github.com/leuschel/bbedit-prob[BBedit Language modules for
 B, TLA+, CSP and Prolog] are available.
 
 [[emacs]]
-==== Emacs
+=== Emacs
 
 A package is available. //TODO: Downloadlink  b-mode.el.zip[]

src/docs/chapter/user/10_General/GeneralPresentation.adoc

+
 [[general-presentation]]
-== General Presentation
+= General Presentation
 
 [[the-prob-main-window]]
-=== The ProB Main Window
+== The ProB Main Window
 
 The menu bar contains the various commands to access the features of
 ProB. It includes the traditional _File_ menu with a sub-menu "Recent
@@ -37,7 +38,7 @@ mean);
 3.  The history of operations leading to this state (History).
 
 [[general-presentation-preferences]]
-=== Preferences
+== Preferences
 
 The _Preferences_ menu allows the various features of ProB to be
 configured. When ProB is started for the first time, it creates a file

src/docs/chapter/developer/Getting_Involved.adoc → src/docs/chapter/user/10_General/Getting_Involved.adoc

+
 [[getting-involved]]
 = Getting Involved
 
-
 [[the-prob-java-core-and-ui]]
 == The ProB Java Core and UI
 

src/docs/chapter/user/10_General/ProB_Logic_Calculator_old.adoc

+
 [[prob-logic-calculator]]
-== ProB Logic Calculator
+= ProB Logic Calculator
+
+WARNING: This section is relatively old and may contain errors.
 
 Below is a ProB-based http://research.microsoft.com/en-us/um/people/lamport/tla/logic-calculators.html[logic
 calculator]. You can enter predicates and expressions in the upper
@@ -28,7 +31,7 @@ versions available for Linux and Mac (the above calculator only uses the
 32-bit version).
 
 [[short-syntax-guide-for-b-constructs]]
-=== Short syntax guide for some of B's constructs:
+== Short syntax guide for some of B's constructs:
 
 * comments `/* ... */`
 * conjunction `P & Q`, disjunction `P or Q`, implication `P \=> Q`,
@@ -91,7 +94,7 @@ https://www3.hhu.de/stups/downloads/pdf/PlaggeLeuschel_Kodkod2012.pdf[ProB-Kodko
 backend] instead of the default constraint-logic programming kernel.
 
 [[small-tutorial]]
-=== Small Tutorial
+== Small Tutorial
 
 Here is a small tutorial to get you started. B distinguishes
 expressions, which have a value, and predicates which can be either true
@@ -209,7 +212,7 @@ will refine ProB's output to also indicate when the
 solution/counter-example is still guaranteed to be correct)!
 
 [[executing-the-calculator-locally]]
-=== Executing the Calculator locally
+== Executing the Calculator locally
 
 You can evaluate formulas on your machine in the same way as the
 calculator above, by <<downloads,downloading ProB>> (ideally a nightly

src/docs/chapter/developer/30_tcltk/ZZ_section_footer.adoc → src/docs/chapter/user/10_General/ZZ_section_footer.adoc

+
 :leveloffset: -1

src/docs/chapter/user/11_BLanguage/00_BLanguage.adoc → src/docs/chapter/user/11_BLanguage/00_section_header.adoc

+
 [[b-language]]
 = B Language
+:leveloffset: +1

src/docs/chapter/user/11_BLanguage/01_Summary_of_B_Syntax.adoc

+
 [[summary-of-b-syntax]]
-== Summary of B Syntax
+= Summary of B Syntax
 
 [[logical-predicates]]
-=== Logical predicates:
+== Logical predicates:
 
 ....
  P & Q       conjunction
@@ -20,7 +21,7 @@ Note: you can also introduce multiple variables inside a universal or
 existential quantification, e.g., `!(x,y).(P => Q)`.
 
 [[equality]]
-=== Equality:
+== Equality:
 
 ....
  E = F      equality
@@ -28,7 +29,7 @@ existential quantification, e.g., `!(x,y).(P => Q)`.
 ....
 
 [[booleans]]
-=== Booleans:
+== Booleans:
 
 ....
  TRUE
@@ -44,7 +45,7 @@ values `x` and `y` using conjunction you have to write
 value you have to use `bool(z>0)`.
 
 [[sets]]
-=== Sets:
+== Sets:
 
 ....
  {}              empty set
@@ -73,7 +74,7 @@ value you have to use `bool(z>0)`.
 ....
 
 [[numbers]]
-=== Numbers:
+== Numbers:
 
 ....
  INTEGER        set of integers
@@ -104,7 +105,7 @@ value you have to use `bool(z>0)`.
 ....
 
 [[relations]]
-=== Relations:
+== Relations:
 
 ....
  S<->T         relation
@@ -134,7 +135,7 @@ value you have to use `bool(z>0)`.
 ....
 
 [[functions]]
-=== Functions:
+== Functions:
 
 ....
   S+->T          partial function
@@ -151,7 +152,7 @@ value you have to use `bool(z>0)`.
 ....
 
 [[sequences]]
-=== Sequences:
+== Sequences:
 
 ....
   <> or []   empty sequence
@@ -178,7 +179,7 @@ value you have to use `bool(z>0)`.
 ....
 
 [[records]]
-=== Records:
+== Records:
 
 ....
   struct(ID:S,...,ID:S)   set of records with given fields and field types
@@ -187,7 +188,7 @@ value you have to use `bool(z>0)`.
 ....
 
 [[strings]]
-=== Strings:
+== Strings:
 
 ....
   "astring"       a specific (single-line) string value
@@ -219,7 +220,7 @@ tabs and newlines. ProB assumes that all B machines and strings use the
 UTF-8 encoding.
 
 [[trees]]
-=== Trees:
+== Trees:
 
 Nodes in the tree are denoted by index sequences (branches), e.g,
 n=[1,2,1] Each node in the tree is labelled with an element from a
@@ -248,7 +249,7 @@ domain S.
 ....
 
 [[let-and-if-then-else]]
-=== LET and IF-THEN-ELSE
+== LET and IF-THEN-ELSE
 
 ProB allows the following for predicates and expressions:
 
@@ -260,7 +261,7 @@ ProB allows the following for predicates and expressions:
 Note: The expressions E1,... defining x1,... are not allowed to use x1,...
 
 [[statements-aka-substitutions]]
-=== Statements (aka Substitutions):
+== Statements (aka Substitutions):
 
 ....
   skip         no operation
@@ -294,7 +295,7 @@ Note: The expressions E1,... defining x1,... are not allowed to use x1,...
 ....
 
 [[machine-header]]
-=== Machine header:
+== Machine header:
 
 ....
   MACHINE or REFINEMENT or IMPLEMENTATION
@@ -307,7 +308,7 @@ Note: The expressions E1,... defining x1,... are not allowed to use x1,...
 ....
 
 [[machine-sections]]
-=== Machine sections:
+== Machine sections:
 
 ----
   CONSTRAINTS         P      (logical predicate)
@@ -325,7 +326,7 @@ Note: The expressions E1,... defining x1,... are not allowed to use x1,...
 ----
 
 [[machine-inclusion]]
-=== Machine inclusion:
+== Machine inclusion:
 
 ....
   USES list of machines
@@ -343,7 +344,7 @@ Note: The expressions E1,... defining x1,... are not allowed to use x1,...
 ....
 
 [[definitions]]
-=== Definitions:
+== Definitions:
 
 ....
   NAME1 == Expression;          Definition without arguments
@@ -378,7 +379,7 @@ There are a few Definitions which can be used to influence the animator:
 ....
 
 [[comments-and-pragmas]]
-=== Comments and Pragmas
+== Comments and Pragmas
 
 ....
 B supports two styles of comments:
@@ -408,7 +409,7 @@ The whitespace between @ and PRAGMA is optional.
 ----
 
 [[file-extensions]]
-=== File Extensions
+== File Extensions
 
 ....
    .mch   for abstract machine files
@@ -419,7 +420,7 @@ The whitespace between @ and PRAGMA is optional.
 ....
 
 [[differences-with-atelierbb4free]]
-=== Differences with AtelierB/B4Free
+== Differences with AtelierB/B4Free
 
 Basically, ProB tries to be compatible with Atelier B and conforms to
 the semantics of Abrial's B-Book and of
@@ -466,7 +467,7 @@ AtelierB/ProB:
  - In AtelierB/ProB the BOOL type is pre-defined and cannot be redefined
 
 [[other-notes]]
-=== Other notes
+== Other notes
 ProB is best at treating universally quantified formulas of the form `!x.(x:SET => RHS)`,
 or  `!(x,y).(x|->y:SET =>RHS)`, `!(x,y,z).(x|->y|->z:SET =>RHS)`, ...;+
 otherwise the treatment of `!(x1,...,xn).(LHS => RHS)` may delay until all values treated by LHS are known. +

src/docs/chapter/user/11_BLanguage/02_Types.adoc

+
 [[types]]
-== Types
+= Types
 
 ProB requires all constants and variables to be typed. As of version
 1.3, ProB uses a new unification-based type inference and checking
@@ -10,7 +11,7 @@ adding additional typing predicates). Also note that, in contrast to
 Atelier B, ProB will type check macro DEFINITIONS.
 
 [[what-is-a-basic-type-in-b]]
-=== What is a basic type in B
+== What is a basic type in B
 
 * BOOL
 * INTEGER
@@ -20,7 +21,7 @@ parameter of the machine
 * τ1 * τ2 (Cartesian product) for τ1 and τ2 being two types
 
 [[what-needs-to-be-typed]]
-=== What needs to be typed
+== What needs to be typed
 
 Generally speaking, any constant or variable. More precisely:
 
@@ -46,7 +47,7 @@ ProB will warn you if a variable has not been given a type.
 inferred for your constants and global variables.*
 
 [[restriction-on-the-domains-of-the-variables]]
-=== Restriction on the Domains of the Variables
+== Restriction on the Domains of the Variables
 
 Animating and verifying a B specification is in principle undecidable.
 ProB overcomes this by requiring that the domain of the variables is
@@ -72,7 +73,7 @@ ProB, provided it is of a simple form `card(S)=Nr`, where `S` is a deferred
 set and `Nr` a natural number.
 
 [[enumeration-in-prob]]
-=== Enumeration in ProB
+== Enumeration in ProB
 
 The typing information is used by ProB to enumerate the possible values
 of a constant or a variable whenever a specification does not narrow