Merge pull request #348 from triska/master

update the toplevel description, incorporating the latest changes

README.md

@@ -124,61 +124,56 @@ The optional `--release` flag will perform various optimizations,
 producing a faster executable.
 
 ## Tutorial
-To enter a multi-clause predicate, the directive "[user]" is used.
 
-For example,
-```
-?- [user].
-(type Enter + Ctrl-D to terminate the stream when finished)
-p(f(f(X)), h(W), Y) :- g(W), h(W), f(X).
-p(X, Y, Z) :- h(Y), z(Z).
-?- [user].
-(type Enter + Ctrl-D to terminate the stream when finished)
-h(x). h(y).
-h(z).
-```
-In the example, `Enter + Ctrl-D` is used to terminate the standard
-input stream. The instructive message is always printed.
+Prolog files are loaded by specifying them as arguments on the command
+line. For example, to load `program.pl`, use:
 
-Queries are issued as
 ```
-?- p(X, Y, Z).
+$> scryer-prolog program.pl
 ```
 
-Pressing `SPACE` will backtrack through other possible answers, if any exist.
-Pressing `.` will abort the search and return to the prompt.
+Loading a Prolog file is also called “consulting” it. The built-in
+predicate `consult/1` can be used to consult a file from within
+Prolog:
 
-Wildcards work as well:
+```
+?- consult('program.pl').
+```
+
+As an abbreviation for `consult/1`, you can specify a *list* of
+program files, given as *atoms*:
+
+```
+?- ['program.pl'].
+```
+
+The special notation `[user]` is used to read Prolog text from
+standard input. For example,
 
 ```
 ?- [user].
-(type Enter + Ctrl-D to terminate the stream when finished)
-member(X, [X|_]).
-member(X, [_|Xs]) :- member(X, Xs).
-?- member(X, [a, b, c]).
-   X = a
-;  X = b
-;  X = c
-;  false.
-```
-and so do conjunctive queries:
-```
-?- [user].
-(type Enter + Ctrl-D to terminate the stream when finished)
-f(X) :- g(X).
-g(x). g(y). g(z).
-h(call(f, X)).
-?- h(X), X.
-   X = call(f,x)
-;  X = call(f,y)
-;  X = call(f,z).
+hello(declarative_world).
+hello(pure_world).
 ```
 
-Note that the values of variables belonging to successful queries are
-printed out, on one line each. Uninstantiated variables are denoted by
-a number preceded by an underscore (`X = _0` in an example above).
+Pressing `RETURN` followed by `Ctrl-d` stops reading from
+standard input and consults the entered Prolog text.
+
+After a program is consulted, you can ask *queries* about the
+predicates it defines. For example, with the program shown above:
+
+```
+?- hello(What).
+   What = declarative_world
+;  What = pure_world.
+```
+
+Press `SPACE` to show further answers, if any exist. Press `.` to
+abort the search and return to the toplevel prompt.
+Press `h` to show a help message.
+
+To quit Scryer Prolog, use the standard predicate `halt/0`:
 
-To quit scryer-prolog, type
 ```
 ?- halt.
 ```