swish/commit

Added the help files.

authorJan Wielemaker
Fri Sep 19 19:19:08 2014 +0200
committerJan Wielemaker
Fri Sep 19 19:19:08 2014 +0200
commitd080ee89fcb1a0a4972bba28719a1be478e63c4d
treee6774badf3aa612180cc82bb7c3118a7acbbf7a4
parentfa18738456d57be08342ce2b303babdd1d50d0c6
Diff style: patch stat
diff --git a/Makefile b/Makefile
index 6020389..987edf7 100644
--- a/Makefile
+++ b/Makefile
@@ -2,19 +2,22 @@
 
 DIRS=lib/swish
 LIBS=lib/swish/storage.pl lib/swish/page.pl lib/swish/help.pl \
-     lib/swish/examples.pl lib/swish/authenticate.pl \
-     lib/swish/config.pl
+     lib/swish/examples.pl lib/swish/config.pl
 JS=web/js/swish-min.js web/js/require.js
 CSS=web/css/swish-min.css
 ICONS=web/icons/owl_25_years.png \
       web/icons/dead.png web/icons/error.png web/icons/running.gif
+HELP=web/help/about.html web/help/caveats.html web/help/help.html \
+     web/help/query.html web/help/runner.html
 
-all:	$(DIRS) $(LIBS) $(JS) $(CSS) $(ICONS)
+all:	$(DIRS) $(LIBS) $(JS) $(CSS) $(ICONS) $(HELP)
 
 lib/swish:
 	mkdir -p $@
 web/icons:
 	mkdir -p $@
+web/help:
+	mkdir -p $@
 
 lib/swish/config.pl: src/lib/config.pl lib/swish
 	rsync -u $< $@
@@ -26,8 +29,6 @@ lib/swish/help.pl: src/lib/help.pl lib/swish
 	rsync -u $< $@
 lib/swish/examples.pl: src/lib/examples.pl lib/swish
 	rsync -u $< $@
-lib/swish/authenticate.pl: src/lib/authenticate.pl lib/swish
-	rsync -u $< $@
 
 web/js/swish-min.js: src/web/js/swish-min.js
 	rsync -u $< $@
@@ -45,3 +46,14 @@ web/icons/running.gif: src/web/icons/running.gif web/icons
 	rsync -u $< $@
 web/icons/owl_25_years.png: src/web/icons/owl_25_years.png web/icons
 	rsync -u $< $@
+
+web/help/about.html: src/web/help/about.html web/help
+	rsync -u $< $@
+web/help/caveats.html: src/web/help/caveats.html web/help
+	rsync -u $< $@
+web/help/help.html: src/web/help/help.html web/help
+	rsync -u $< $@
+web/help/query.html: src/web/help/query.html web/help
+	rsync -u $< $@
+web/help/runner.html: src/web/help/runner.html web/help
+	rsync -u $< $@
diff --git a/web/help/about.html b/web/help/about.html
new file mode 100644
index 0000000..7306993
--- /dev/null
+++ b/web/help/about.html
@@ -0,0 +1,22 @@
+<!DOCTYPE HTML>
+
+<html>
+  <head>
+  <title>About SWISH</title>
+  </head>
+  <body>
+
+<p>
+
+<span style="color:darkblue">SWI</span><span style="color:maroon">SH</span>
+was originally written by Torbjörn Lager as a homage to SWI-Prolog. Jan 
+Wielemaker designed and implemented the present version.
+<span style="color:darkblue">SWI</span><span style="color:maroon">SH</span>
+now serves also as a demo the Pengines platform. You are free to use it
+ as a starting point for your own project.
+
+</body>
+</html>
+
+
+
diff --git a/web/help/caveats.html b/web/help/caveats.html
new file mode 100644
index 0000000..11f9bbe
--- /dev/null
+++ b/web/help/caveats.html
@@ -0,0 +1,57 @@
+<!DOCTYPE HTML>
+
+<html>
+  <head>
+  <title>Caveats of the web version of SWI-Prolog</title>
+  </head>
+  <body>
+<h4>Table of Contents</h4>
+                <ul>
+                    <li><a href="#sandboxing">Sandboxing</a></li>
+                    <li><a href="#io">Input and output</a></li>
+		</ul>
+
+<h4 id="sandboxing">Sandboxing</h4>
+<p>
+SWISH cannot provide unrestricted access to Prolog because Prolog gives
+unrestricted access to the operating system.  Therefore, SWISH examines
+each goal on safety before execution.  This process unfolds the call-tree
+and verifies all called predicates against a whitelist.  It fails on three
+occasions:
+</p>
+
+  <ul>
+    <li>If insufficient information is available to decide what
+        will be called.  E.g., <code>?- read(X), call(X).</code>
+	Such errors are raised as <em>instantiation errors</em>.
+    <li>If a predicate is found that is not whitelisted.  Such
+        errors are raised as <em>permission errors</em>
+    <li>If a called predicate is not defined.  Such errors are
+        raised as <em>existence errors</em>
+  </ul>
+
+<p>
+If any of the above happens, the error is printed, along with
+a chain of intermediate goals that should help finding the culprit.
+Note that the whitelist is incomplete, i.e., there are many
+predicates that can be considered safe that are not on the list.
+Please report such omissions as bugs.
+</p>
+		<h4 id="io">Input and output</h4>
+<p>
+Normal read and write do not work in the web environment.  A number
+of normal Prolog predicates are redefined to provide basic I/O.  Other
+I/O predicate are either not whitelisted or send their output to the
+server's console.
+</p>
+
+  <ul>
+    <li>read/1
+    <li>write/1, writeq/1, print/1, write_canonical/1, write_term/2,
+        portray_clause/1
+    <li>format/1, format/2
+    <li>message_hook/3, redirecting all system messages.
+  </ul>
+
+</body>
+</html>
diff --git a/web/help/help.html b/web/help/help.html
new file mode 100644
index 0000000..4521aeb
--- /dev/null
+++ b/web/help/help.html
@@ -0,0 +1,69 @@
+<!DOCTYPE HTML>
+
+<html>
+  <head>
+  <title>SWISH: SWI-Prolog for SHaring</title>
+  </head>
+<body>
+<h4>Table of Contents</h4>
+  <ul>
+    <li><a href="#motivation">Motivation</a></li>
+    <li><a href="#exampls">Examples</a></li>
+    <li><a href="#time_limit">Time limit</a></li>
+    <li><a href="#known_issues">Known issues</a></li>
+    <li><a href="#technology">Technology</a></li>
+    <li><a href="#source_code">Source code</a></li>
+  </ul>
+
+<h4 id="motivation">Motivation</h4>
+                <p>
+                    <span style="color:darkblue">SWI</span><span style="color:maroon">SH</span> is inspired by web-based tools such as <a target="_blank" href="http://jsfiddle.net/">JSFIDDLE</a> in that it allows you to develop a program and then share it with others on the Web. However, lacking both debugger and profiler, <span style="color:darkblue">SWI</span><span style="color:maroon">SH</span> is far from a full-fledged IDE for Prolog, and to avoid compromising the server it does not allow you to execute "dangerous" predicates such as predicates reading and writing files. (It does however allow you to use predicates such as <code>read/1</code> and <code>write/1</code> but they will only read from and write to your web browser.)
+                </p>
+                <p>
+                    <span style="color:darkblue">SWI</span><span style="color:maroon">SH</span> might be useful in an educational setting. If you are a teacher, you may want to tell your students to share with you the solutions to exercises by sending you a link to <span style="color:darkblue">SWI</span><span style="color:maroon">SH</span> loaded with their solutions ready to run.
+                </p>
+                <p>
+                    Yes, and talking to SWI-Prolog from an iPad or maybe even a smartphone should also work, although it has not been extensively tested yet.
+                </p>
+                <h4 id="exampls">Examples</h4>
+                <p>
+                    If you include example goals inside comments as shown below, they will be used to populate the example menu and make the first goal show in the Goal input field.
+                </p>
+                <pre style="font-size:80%">
+/** Examples
+
+loves(X, mia).
+jealous(X, Y).
+
+*/</pre>
+                <h4 id="time_limit">Time limit</h4>
+                <p>
+                    When you click the First button, your goal will be allowed to execute on the server for 300 seconds before aborting and returning with a message stating that the time limit has been exceeded.
+                </p>
+                <h4 id="known_issues">Known issues</h4>
+                <p>
+                <ul>
+                    <li><span style="color:darkblue">SWI</span><span style="color:maroon">SH</span> works fine in Safari, Firefox and Chrome. I have not tested it in Internet Explorer, so I don't know if it works there.
+                    </li>
+                    <li>The syntax highlighting of Prolog source code as provided by the <a target="_blank" href="http://ace.ajax.org/">ACE editor</a> is slightly off sometimes. The relevant file is <a target="_blank" href="/vendor/src-noconflict/mode-prolog.js">here</a>. Please send a copy to <a target="_blank" href="mailto:torbjorn.lager@gmail.com">me</a> if you are able to fix any of the highlighting issues.
+                    </li>
+                </ul>
+                <h4 id="technology">Technology</h4>
+                <p>
+                    <span style="color:darkblue">SWI</span><span style="color:maroon">SH</span> is implemented in a combination of Prolog, HTML, CSS and JavaScript. The only framework used is <a target="_blank" href="http://getbootstrap.com/">Bootstrap</a> and the choice of editor landed on the very capable <a target="_blank" href="http://ace.ajax.org/">ACE editor</a>. The server serves static HTML, CSS and JavaScript code only, none of that is dynamically generated on the server. Instead, to create behaviour, the main traffic between server and client consists of the JSON responses from the server guiding the transformation of the browser's DOM on the client side.
+                </p>
+
+                <h4 id="source_code">Source code</h4>
+                <p>
+                    The source code for <span style="color:darkblue">SWI</span><span style="color:maroon">SH</span> is available in the Pengine distribution on <a target="_blank" href="https://github.com/SWI-Prolog/pengines">GitHub</a>.
+                </p>
+</body>
+</html>
+
+
+
+
+
+
+
+
diff --git a/web/help/query.html b/web/help/query.html
new file mode 100644
index 0000000..507a7ff
--- /dev/null
+++ b/web/help/query.html
@@ -0,0 +1,30 @@
+<!DOCTYPE HTML>
+
+<html>
+  <head>
+  <title>Entering a Prolog query</title>
+  </head>
+  <body>
+
+<p>
+The <b>Run!</b> button sends the query from the query editor and the
+program from the program editor for evaluation to the Prolog server.
+
+<p>
+You can either type a query or embed queries in a comment block in the
+program and select it from the <b>Examples</b> dropup menu. Queries are
+added to the <b>History</b> dropup menu for re-use.
+
+<p>
+Example queries embedded in your program must be formatted like this:
+
+<pre class="prolog">
+/** &lt;examples&gt;
+
+?- run.
+?- known(X).
+*/
+</pre>
+
+</body>
+</html>
diff --git a/web/help/runner.html b/web/help/runner.html
new file mode 100644
index 0000000..d830504
--- /dev/null
+++ b/web/help/runner.html
@@ -0,0 +1,83 @@
+<!DOCTYPE HTML>
+
+<html>
+  <head>
+  <title>Running a query</title>
+  </head>
+  <body>
+
+<style>
+table.runner-states {
+  border: 1px solid #ccc;
+  width: 90%;
+  margin: auto;
+}
+table.runner-states th {
+  font-style:italic;
+  white-space:nowrap;
+  padding-right:2em;
+  padding-left:5px;
+  vertical-align:top;
+}
+table.runner-states tr:nth-child(even) {
+  background-color: #eee;
+}
+table.runner-states tr.group th {
+  color: #fff;
+  background-color: #aaa;
+  text-align: center;
+}
+</style>
+
+<h4>Keyboard shortcuts</h4>
+
+  <table class="runner-states">
+  <tr><th>";", &lt;space&gt;</th><td>Next</td>
+  <tr><th>".", &lt;Enter&gt;</th><td>Stop</td>
+  <tr><th>"a", &lt;Esc&gt;</th><td>Stop or abort</td>
+  <tr><th>&lt;Del&gt;</th><td>Close</td>
+  <tr><th>&lt;F1&gt;</th><td>Help (this page)</td>
+  </table>
+
+<h4>Running states</h4>
+
+  <table class="runner-states">
+  <tr class="group"><th colspan="2">Living states</th>
+  <tr><th>Running</th><td>
+  The query has been sent to the server and is being executed.  This
+  state is indicated by the rotating icon.
+  </td>
+  <tr><th>Wait next</th><td>
+  The query succeeded with a <i>choice point</i> and waits for the
+  user, providing the options <b>Next</b> (give me another answer)
+  and <b>Stop</b> (I'm happy and I don't want any more anwers).
+  </td>
+  <tr><th>Wait input</th><td>
+  The query called read/1 and waits for user input.  The runner shows
+  an input element.  The user must type a valid Prolog term and press
+  <b>Enter</b>.
+  </td>
+  <tr class="group"><th colspan="2">Completed (dead) states</th>
+  <tr><th>True</th><td>
+  The query succeeded and there are no more answers.
+  </td>
+  <tr><th>False</th><td>
+  The query failed.
+  </td>
+  <tr><th>Error</th><td>
+  The query terminated due to a runtime error (exception).
+  </td>
+  <tr><th>Stopped</th><td>
+  The user selected <b>Stop</b>
+  </td>
+  <tr><th>Aborted</th><td>
+  The query was aborted by the user.
+  </td>
+  </table>
+
+<hr>
+<p>
+Note that at maximum, three queries can be open at the same time.
+
+</body>
+</html>