add motivation and comments about library(pio) predicates

diff --git a/src/lib/pio.pl b/src/lib/pio.pl
index 25a2cba80cf2def773a9b5086ac51d81cab4f592..18ceaab5b57470c6e2eda507bcd5d09ce6aa5831 100644 (file)
--- a/src/lib/pio.pl
+++ b/src/lib/pio.pl
@@ -1,3 +1,14 @@
+/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+   Pure I/O
+   ========
+
+   Our goal is to encourage the use of definite clause grammars (DCGs)
+   for describing strings. The predicates phrase_from_file/[2,3],
+   phrase_to_file/2 and phrase_to_stream/2 let us apply DCGs transparently
+   to files and streams, and therefore decouple side-effects from
+   declarative descriptions.
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
+
 :- module(pio, [phrase_from_file/2,
                 phrase_from_file/3,
                 phrase_to_file/2,
@@ -16,6 +27,13 @@
 :- meta_predicate(phrase_to_file(2, ?)).
 :- meta_predicate(phrase_to_stream(2, ?)).
 
+/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+   phrase_from_file(GRBody, File)
+
+   True if grammar rule body GRBody covers the contents of File,
+   represented as a list of characters.
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
+
 phrase_from_file(NT, File) :-
     phrase_from_file(NT, File, []).