diff --git a/reference/parle/book.xml b/reference/parle/book.xml
index 5e54101b2e..d99c700a4d 100644
--- a/reference/parle/book.xml
+++ b/reference/parle/book.xml
@@ -8,10 +8,16 @@
&reftitle.intro;
- The parle extension provides lexing and parsing facilities. The implementation is based on Ben Hanson's libraries and requires a C++14 capable compiler. The lexer is based on the regex matching, the parser is LALR(1). Lexers and parsers are generated on the fly and can be used immediately after they've been finalized. Serialization and code generation are not supported by the extension, yet.
+ The parle extension provides lexing and parsing facilities. The implementation is based on Ben Hanson's libraries and requires a C++14 capable compiler. The lexer is based on the regex matching, the parser is LALR(1). Lexers and parsers are generated on the fly and can be used immediately after they've been finalized. Parle deals with parsing and lexing, maintanance of tree structures and other processing are the implementer's task. Serialization and code generation are not supported by the extension, yet.
+
+
+ The use case for parle is, when a data format is too complex to be handled by the regex matching with PCRE. The practical application is wide - starting with things like complex CSV data, processing custom data formats and beyond. The helper methods such as Parle\Lexer::dump to inspect the generated state machine, or Parle\Parser::dump to inspect the generated grammar, are useful. The method Parle\Parser::trace can also be used to track the parsing operation.
- Lexer analysis is a process of splitting a character sequence into a list of lexemes. The lexeme list can be then used for the syntax analysis against a formal grammar. These operations are also known as lexing and parsing. This documentation doesn't provide any exhaustive information on lexing and parsing, as there are numerous resources on the net touching this topic. The approach of the underlaying libraries used in parle is in most cases compatible to Flex, Bison and other similar tools. It is also useful to use Parle\Lexer::dump to inspect the generated state machine, or Parle\Parser::dump to inspect the generated grammar. The method Parle\Parser::trace can be also useful to trace the parsing operation.
+ Lexer analysis is a process of splitting a character sequence into a list of lexemes. The lexeme list can be then used for the syntax analysis against a formal grammar. These operations are also known as lexing and parsing. This documentation doesn't aim to provide an exhaustive information on lexing and parsing. The basics can be found on the numerous resources on the net. Several usage examples are included, to show the functionality. The extension is also useful for PHP programmers willing to learn parsing and lexing.
+
+
+ The approach of the underlaying libraries used in parle is in most cases compatible to Flex, Bison and other similar tools. The substantial difference from the aforementioned tools is, that lexers and parsers are produced at the runtime and can be used immediately. Thanks to the underlying libraries, the underlaying work is still done by the parle extension, thus allowing for good efficiency. When the case complexity is irreducible with PCRE, parle sure comes into the game to handle sophisticated data structures. Nevertheless, in many cases there can be also a win for the cases even with the smaller complexity in terms or memory usage and maintainability.
diff --git a/reference/parle/parle.lexer.xml b/reference/parle/parle.lexer.xml
index 83962fcd94..65e87c71b3 100644
--- a/reference/parle/parle.lexer.xml
+++ b/reference/parle/parle.lexer.xml
@@ -12,7 +12,7 @@
&reftitle.intro;
-
+ Base lexer class. Lexemes can be defined on the fly. If the particular lexer instance is meant to be used with Parle\Parser, the token IDs need to be taken from there. Otherwise, arbitrary token IDs can be supplied.
diff --git a/reference/parle/parle.parser.xml b/reference/parle/parle.parser.xml
index eaa605e994..c4bc49fdcd 100644
--- a/reference/parle/parle.parser.xml
+++ b/reference/parle/parle.parser.xml
@@ -12,7 +12,7 @@
&reftitle.intro;
-
+ Parser class. Rules can be defined on the fly. Once finalized, a Parle\Lexer instance is required to deliver the token stream.
diff --git a/reference/parle/parle.rlexer.xml b/reference/parle/parle.rlexer.xml
index 866f1b8e87..79de8f8bf8 100644
--- a/reference/parle/parle.rlexer.xml
+++ b/reference/parle/parle.rlexer.xml
@@ -12,7 +12,7 @@
&reftitle.intro;
-
+ Recursive lexer class. Any sub states can be added on the fly to match recursive patterns. Though, sometimes it might be simpler to use an instance of Parle\Lexer and define some parser.