Fix up of bad documentation merge 673b5f9

doc/GettingStarted-Minsky.tex

@@ -202,7 +202,7 @@ \subsubsection{Simulation}
 
 \begin{itemize}
 \item Time unit allows one to specify units for the time dimension for
-  dimensional analysis. eg ``year'', ``s'' etc.
+  \htmlref{dimensional analysis}{dimensional analysis}. eg ``year'', ``s'' etc.
 \item Controls aspect of the adaptive Runge-Kutta equation solver, which
 trade off performance and accuracy of the model. 
 \item Note a first order explicit solver is the classic Jacobi method, which is the fastest,
@@ -682,26 +682,54 @@ \subsection{Equations tab}\label{tabs:Equations}
 
 This displays the mathematical representation of the model
 
-\subsection{Parameters tab}\label{tabs:Parameters}
+\subsection{Summary Tab}\label{tabs:Summary}
 
-This displays the properties of all parameters defined in the model,
-in one place.
+This tab provides a summary table of all variables in the system, in a
+heirarchical fashion that can be navigated by expanding or hiding
+sections by toggling the caret. Each variable shows its name, it
+definition, dimensions (for tensor-valued variables), initial
+expression, units and current value.
 
-\subsection{Variables tab}\label{tabs:Variables}
+Most of these fields are editable, and usually do the obvious
+thing. Changing a variable's name will do a {\em replace all
+  instances} operation to update all variables of the same
+name. Changing a variable's definition will replace the wiring graph
+leading into the variable by a \htmlref{user defined function}{UserFunction} containing your
+edited string. At some future point, functionality will be added to
+convert a user defined function into a wiring graph.
 
-This displays the properties of selected variables in the model. The
-variables can be displayed on the tab by selecting ``Display variable
-on tab'' in it's context menu. It may be hidden on the design canvas
-if it is not required for the definition of something else. This can
-be a place to keep less important variables ``out of sight''.
+\subsection{Phillips diagram tab}\label{tabs:Phillips}
 
-\subsection{Plots tab}\label{tabs:Plots}
+This tab implement's Minsky's take on a \htmladdnormallink{Phillips
+  diagram showing the stocks and flows in a monetary
+  economy}{https://en.wikipedia.org/wiki/Phillips_Machine}. The
+Phillips tab shows all the information contained in the Godley tables
+of the model - if there aren't any, this tab will be blank.
 
-Shows all plots in one place
+Initially, all the stocks will be arranged around a circle, with the
+flows shown as connecting arrows showing the current direction of the
+flow. You can move and rotate the stocks, and bend the flows to make a
+pleasing layout. The stocks will be coloured as though filled with a
+fluid like Bill Phillip's original analogue computer, and dynamically
+updated as the simulation proceeds.
 
-\subsection{Godleys tab}\label{tabs:Godleys}
+Publication tabs allow the creation of dashboards to emphasise certain
+aspects of a simulation. For example, you may wish to focus on a
+particular plot or Godley table when running the simulation.
 
-Shows all Godley tables in one place.
+Multiple publication tabs can be created by clicking the '+' tab.
+
+Any item from the wiring tab can be added to a publication tab, and
+then moved, resized or rotated independently of the item on the wiring
+tab. For items that dynamically update, the publication tab will be
+updated dynamically during the simulation.
+
+Textual annotation can be added to the publication tab, independently
+of any annotations on the wiring tab.
+
+Wires cannot be added to the publication tab, however you can insert
+arrows (eg $\rightarrow$) by typing the LaTeX text \verb+\rightarrow+,
+and then rotate and scale the arrow to connect parts of the dashboard together.
 
 \subsection{Wires}
 \label{Wires}
@@ -791,8 +819,8 @@ \subsection{Inserting a model component}
   name (eg \verb+sin+, or \verb+*+). Notes can be inserted by starting
   the note with a \verb+#+ character.
 
-\item Variables can also be picked from the \hyperref[ref]{Variable
-    Browser}{Variable Browser}{}{VariableBrowser} and placed on the canvas.
+\item Variables can also be picked from the \htmlref{Variable
+    Browser}{VariableBrowser} and placed on the canvas.
 \end{enumerate}
 
 

doc/Reference.tex

@@ -9,14 +9,20 @@ \subsection{Special
 Some special constants ($e=2.72\ldots$, $\pi=3.14\ldots$, 0, 1, $\infty$) can be placed on the canvas, via two methods:
 
 \begin{itemize}
-\item By clicking on the relevant icon on the Fundamental Constants toolbar; or
-\item By typing the constant name on the canvas, and pressing Enter (or clicking OK) in the variable definition window. These names are: \textit{Euler} for $e=2.72\ldots$; \textit{pi} for $\pi=3.14\ldots$; and \textit{inf} for $\infty$.
+\item By clicking on the relevant icon on the Fundamental Constants
+  toolbar; or
+\item By typing the constant name on the canvas, and pressing Enter
+  (or clicking OK) in the variable definition window. These names are:
+  \textit{Euler} for $e=2.72\ldots$; \textit{pi} for $\pi=3.14\ldots$;
+  and \textit{inf} for $\infty$.
 \end{itemize}
 
 
 \includegraphics{images/FundamentalConstants.png} 
 
-\subsection{Percent} \label{Operation:percent} The percent operator takes one input, and multiplies its elements by 100. It is useful for converting fractions into percentages for display purposes.
+\subsection{Percent} \label{Operation:percent} The percent operator
+takes one input, and multiplies its elements by 100. It is useful for
+converting fractions into percentages for display purposes.
 
 \includegraphics{images/PercentOperator.png} 
 
@@ -30,7 +36,8 @@ \subsection{Percent} \label{Operation:percent} The percent operator takes one in
 
 \subsection{add +}\label{Operation:add} Add multiple numbers together.
 
-The input ports allow multiple wires, which are all summed. If an input port is unwired, it is equivalent to setting it to zero.
+The input ports allow multiple wires, which are all summed. If an
+input port is unwired, it is equivalent to setting it to zero.
 
 \includegraphics{images/PlusSymbol.png} 
 
@@ -42,7 +49,12 @@ \subsection{add +}\label{Operation:add} Add multiple numbers together.
 \end{itemize}
 
 
-\subsection{subtract $-$}\label{Operation:subtract} Subtract two numbers. The input ports allow multiple wires, which are summed prior to the subtraction being carried out. If an input port is unwired, it is equivalent to setting it to zero. Note the small `+' and `$-$' signs on the input ports indicating which terms are added or subtracted from the result.
+\subsection{subtract $-$}\label{Operation:subtract} Subtract two
+numbers. The input ports allow multiple wires, which are summed prior
+to the subtraction being carried out. If an input port is unwired, it
+is equivalent to setting it to zero. Note the small `+' and `$-$'
+signs on the input ports indicating which terms are added or
+subtracted from the result.
 
 \includegraphics{images/MinusKey.png} 
 
@@ -63,9 +75,16 @@ \subsection{multiply $\times$}\label{Operation:multiply} Multiply numbers with e
 
 \begin{itemize}
 \item From the Binary Operations toolbar; or
-\item By pressing the multiply (asterisk: *) key anywhere on the wiring canvas.
+\item By pressing the multiply (asterisk: *) key anywhere on the
+  wiring canvas.
 \end{itemize}
-\subsection{divide $\div$}\label{Operation:divide} Divide a number by another. The input ports allow multiple wires, which are multiplied together prior to the division being carried out. If an input port is unwired, it is equivalent to setting it to one. Note the small `$\times$' and `$\div$' signs indicating which port refers to the numerator and which the denominator.
+
+\subsection{divide $\div$}\label{Operation:divide} Divide a number by
+another. The input ports allow multiple wires, which are multiplied
+together prior to the division being carried out. If an input port is
+unwired, it is equivalent to setting it to one. Note the small
+`$\times$' and `$\div$' signs indicating which port refers to the
+numerator and which the denominator.
 
 \includegraphics{images/DivideKey.png} 
 
@@ -75,19 +94,31 @@ \subsection{divide $\div$}\label{Operation:divide} Divide a number by another. T
 \item From the Binary Operations toolbar; or
 \item By pressing the divide key (/) anywhere on the wiring canvas.
 \end{itemize}
-\subsection{log}\label{Operation:log} Take the logarithm of the $x$ input port, to base $b$. The base $b$ needs to be specified --- if the natural logarithm is desired ($b=e$), use the \htmlref{ln operator}{Operation:ln} instead.
+
+\subsection{log}\label{Operation:log} Take the logarithm of the $x$
+input port, to base $b$. The base $b$ needs to be specified --- if the
+natural logarithm is desired ($b=e$), use the \htmlref{ln
+  operator}{Operation:ln} instead.
 
 \includegraphics{images/LogKey.png} 
 
 The operator can be placed on the canvas in two ways:
 
 \begin{itemize}
 \item From the Binary Operations toolbar; or
-\item By typing the word "log" anywhere on the wiring canvas, and then pressing the Enter key.
+\item By typing the word ``log'' anywhere on the wiring canvas, and then
+  pressing the Enter key.
 \end{itemize}
-When you use the direct typing method to enter the Log operator, the text entry window pops up. This allows you to type a variable/parameter name starting with Log (like, for example, "Logical". If you press Enter (or click on OK) with only the word Log in the window, the Log operator will be placed on the canvas.
 
-\subsection{pow $x^y$}\label{Operation:pow} Raise one number to the power of another. The ports are labelled $x$ and $y$, referring the the formula $x^y$.
+When you use the direct typing method to enter the log operations, the
+text entry window pops up. This allows you to type a
+variable/parameter name starting with log (like, for example,
+``logical''. If you press Enter (or click on OK) with only the word log
+in the window, the log operation will be placed on the canvas.
+
+\subsection{pow $x^y$}\label{Operation:pow} Raise one number to the
+power of another. The ports are labelled $x$ and $y$, referring the
+the formula $x^y$.
 
 \includegraphics{images/PowerKey.png} 
 
@@ -96,7 +127,8 @@ \subsection{pow $x^y$}\label{Operation:pow} Raise one number to the power of ano
 
 \begin{itemize}
 \item From the Binary Operations toolbar; or
-\item By typing the word "Pow" anywhere on the wiring canvas and then pressing the Enter Key (or clicking on OK).
+\item By typing the word ``pow'' anywhere on the wiring canvas and then
+  pressing the Enter Key (or clicking on OK).
 \end{itemize}
 
 \subsection{lt $<$}\label{Operation:lt} Returns 0 or 1, depending on whether $x<y$ is true (1) or false (0).
@@ -107,32 +139,37 @@ \subsection{lt $<$}\label{Operation:lt} Returns 0 or 1, depending on whether $x<
 
 \begin{itemize}
 \item From the Binary Operations toolbar; or
-\item By typing the letters "lt" on the canvas and then pressing the Enter key.
+\item By typing the letters ``lt'' on the canvas and then pressing the Enter key.
 \end{itemize}
 
 
-\subsection{le $\le$}\label{Operation:le} Returns 0 or 1, depending on whether $x\le y$ is true (1) or false (0).
+\subsection{le $\le$}\label{Operation:le} Returns 0 or 1, depending on
+whether $x\le y$ is true (1) or false (0).
 
 \includegraphics{images/LessEqualKey.png} 
 
 The operator can be placed on the canvas in two ways:
 
 \begin{itemize}
 \item From the Binary Operations toolbar; or
-\item By typing the letters "le" on the canvas and then pressing the Enter key.
+\item By typing the letters ``le'' on the canvas and then pressing the
+  Enter key.
 \end{itemize}
 
 
-\subsection{eq $=$}\label{Operation:eq} Returns 0 or 1, depending on whether $x=y$ is true (1) or false (0).
+\subsection{eq $=$}\label{Operation:eq} Returns 0 or 1, depending on
+whether $x=y$ is true (1) or false (0).
 
 \includegraphics{images/EqualKey.png} 
 
 The operator can be placed on the canvas in two ways:
 
 \begin{itemize}
 \item From the Binary Operations toolbar; or
-\item By typing the letters "eq" on the canvas and then pressing the Enter key.
+\item By typing the letters ``eq'' on the canvas and then pressing the
+  Enter key.
 \end{itemize}
+
 \subsection{min}\label{Operation:min} Returns the minimum of $x$ and $y$.
 
 \includegraphics{images/minkey.png} 
@@ -141,7 +178,8 @@ \subsection{min}\label{Operation:min} Returns the minimum of $x$ and $y$.
 
 \begin{itemize}
 \item From the Binary Operations toolbar; or
-\item By typing the letters "min" on the canvas and then pressing the Enter key.
+\item By typing the letters ``min'' on the canvas and then pressing
+  the Enter key.
 \end{itemize}
 
 \subsection{max}\label{Operation:max} Returns the maximum of $x$ and $y$.
@@ -156,18 +194,22 @@ \subsection{and $\wedge$}\label{Operation:and_} Logical and of $x$ and $y$, wher
 
 \begin{itemize}
 \item From the Binary Operations toolbar; or
-\item By typing the letters "and\_" on the canvas and then pressing the Enter key.
+\item By typing the letters ``and\_'' on the canvas and then pressing
+  the Enter key. Note the trailing underscore is required because
+  \verb+and+ is a reserved word in C++!
 \end{itemize}
 
 
-\subsection{or $\vee$}\label{Operation:or_} Logical or of $x$ and $y$, where $x\le0.5$
-means false, and $x>0.5$ means true. The output is 1 or 0, depending
-on the result being true (1) or false (0) respectively.
+\subsection{or $\vee$}\label{Operation:or_} Logical or of $x$ and $y$,
+where $x\le0.5$ means false, and $x>0.5$ means true. The output is 1
+or 0, depending on the result being true (1) or false (0)
+respectively.
 
-\subsection{not $\neg$}\label{Operation:not_} The output is 1 or 0, depending
+\subsection{not $\neg$}\label{Operation:not_} The output is 1 or 0,
+depending
 on whether $x\le0.5$ is true (1) or false (0) respectively.
 
-\subsection{time $t$}\label{Operation:time}  Returns the current value
+\subsection{time $t$}\label{Operation:time} Returns the current value
 of system time.
 
 \subsection{Gamma $\Gamma$}\label{Operation:Gamma} Returns the Gamma
@@ -202,52 +244,7 @@ \subsection{differentiate $d/dt$}\label{Operation:differentiate}
 Symbolically differentiates its input with respect to system time,
 producing d/dt[input].  For further explanation regarding
 differentiation, see
-\href{https://en.wikipedia.org/wiki/Derivative}{this wikipedia page}.
-
-% \subsection{data }\label{Operation:data} \buttonIcon{data.eps} A
-% data interpolation widget. The data can be imported from a file
-% containing two values on each line, eg:
-% \begin{quote}
-%   \begin{tabular}{rr}
-%0.1 &0.3\\
-%0.5 &0.7\\
-%0.9 &1\\
-%\end{tabular}
-% \end{quote}
-%
-% If the input is less than the minimum key value (0.1 here), then the
-% operation outputs the corresponding value (0.3). Similarly if the
-% input is greater than the maximum (0.9), the corresponding value (1)
-% is output. If it lies in between two keys (eg 0.2), the the output
-% is linearly interpolated (0.4).
-%
-% Alternatively, the data block can be initialised by a random number
-% generator, which is a way of introducing random numbers\index{random
-% numbers} into the simulation. The parameters, the minimum and
-% maximum values of the function's domain, and the number of random
-% samples over that domain, are all required.
-%
-% \begin{center}
-%   \begin{tabular}{cc}
-%  \resizebox{5.17cm}{!}{\includegraphics{images/initRandom.eps}} &
-%  \resizebox{0.5\textwidth}{!}{\includegraphics{images/randomExample.eps}}
-%  \end{tabular}
-%\end{center}
-%
-%More formally, a data block is an empirical function, based on a
-% table of pairs of values ($x_i, y_i, i=1\ldots n, x_{i+1}>x_i$) read
-% in from a file. The function's output is linearly interpolated from
-% the data, ie:
-% \begin{displaymath}
-%f(x) = \left\{
-%\begin{array}{cl}
-%y_1 & x < x_1\\
-%y_n & x\geq x_n\\
-%\frac{y_i(x_{i+1}-x)+y_{i+1}(x-x_i)}{x_{i+1}-x_i} & x_i \leq x <
-%x_{i+1}\\
-%\end{array}
-%\right.
-%\end{displaymath}
+\htmladdnormallink{this wikipedia page}{https://en.wikipedia.org/wiki/Derivative}.
 
 \subsection{User defined
   function}\label{Operation:userFunction}\label{UserFunction}