[PATCH] DOC: Elaborate on the description and nature of scripts.

[John Darrington]

        * doct/poke.texi (Scripts): Rewrite.
---
 ChangeLog     |  5 +++++
 doc/poke.texi | 53 +++++++++++++++++++++++++++++++++++++++++++----------
 2 files changed, 48 insertions(+), 10 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 76e82f1..32af3ba 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,10 @@
 2019-12-08 John Darrington <address@hidden>
 
+       * doc/poke.texi (Scripts): Elaborate on what scripts are
+       (and what they are not).
+
+2019-12-08 John Darrington <address@hidden>
+
        * src/pkl-lex. (CHAR): Accept \\ as a CHAR token.
        * testsuite/poke.pkl/chars.pk: Add new test.
        * doc/poke.texi (Characters): Document new escape sequence.
diff --git a/doc/poke.texi b/doc/poke.texi
index bbbad4c..c5c3328 100644
--- a/doc/poke.texi
+++ b/doc/poke.texi
@@ -404,11 +404,49 @@ in poke shall be implemented as regular commands.
 @node Scripts
 @section Scripts
 @cindex scripts
-Files containing one poke command per line (which, as we saw above can
-include Poke statements and expressions) can be loaded at startup
-using the @code{-s} command line option.
+Script files contain poke commands.
+A poke command may be a dot command, a Poke statement or a Poke
+expression.
+Lines starting with @code{#} are comments will be ignored.   However a
+comment must start at the beginning of a line.  Here is an example
+of a script:
 
-The @file{~/.pokerc} startup file is also a poke script.
+@example
+# The following two lines are dot commands
+.load my-pickle.pk
+.set obase 16
+
+# The following line is a Poke statement
+dump :size 0x100#B :from 0x10#B
+
+# The following line is a Poke expression without any side effect.
+# Consequently it is valid, but rather useless.
+4 == 4;
+@end example
+
+A script file contains commands, not Poke code.  This means
+it gets read line by line and commands cannot occupy
+more than one line.  Hence the following is a valid script:
+
+@example
+deftype struct = @{int this; int that;@};
+@end example
+
+@noindent
+but this is not valid as a script file and will provoke an error:
+
+@example
+deftype struct =
+@{
+ int this;
+ int that;
+@};
+@end example
+
+Script files can be loaded at startup using the @code{-s} command
+line option (@pxref{Invoking poke}).
+The @file{~/.pokerc} startup file is also an example of a poke
+script (@pxref{pokerc}).
 
 @node Shebang
 @section Shebang
@@ -789,10 +827,6 @@ Upon invocation poke will read and execute the commands of 
the file
 be disabled by passing @code{-q} or @code{--no-init-file} in the command
 line.
 
-The @file{.pokerc} file contains commands, not Poke code.  This means
-it gets read line by line, and commands cannot occupy more than one
-line.
-
 Example of initialization file:
 
 @example
@@ -800,11 +834,10 @@ Example of initialization file:
 .set endian host
 .set obase 16
 .set pretty-print yes
+pk_dump_cluster_by = 4
 .load ~/.poke.d/mypickles.pk
 @end example
 
-Lines starting with @code{#} are ignored as comments.
-
 @node Styling
 @chapter Styling
 @cindex styled output
-- 
2.11.0