RPA Toolkit
documentation structure improvements.
authorMartin Stoilov <martin@rpasearch.com>
Sun, 3 Jul 2011 06:50:12 +0000 (23:50 -0700)
committerMartin Stoilov <martin@rpasearch.com>
Sun, 3 Jul 2011 06:50:12 +0000 (23:50 -0700)
doc/doxygen/rpa.cfg
rpa/doc/introduction.txt
rpa/doc/main.txt
rpa/doc/rpa_bnf.txt [new file with mode: 0644]
rpa/doc/rpa_dbex.txt [new file with mode: 0644]
rpa/doc/rpa_intro.txt [new file with mode: 0644]
rpa/doc/rpa_main.txt [new file with mode: 0644]
rpa/doc/rpatk_build.txt [new file with mode: 0644]
rpa/rpadbex.h

index 7501e6b..a0981a8 100644 (file)
@@ -96,7 +96,13 @@ INPUT                  = ../../rpa/rpadbex.h \
                          ../../rpa/rparecord.h \
                          ../../rpa/rpaerror.h \
                          ../../rpa/doc/main.txt \
+                         ../../rpa/doc/rpatk_build.txt \
+                         ../../rpa/doc/rpa_main.txt \
+                         ../../rpa/doc/rpa_intro.txt \
+                         ../../rpa/doc/rpa_bnf.txt \
+                         ../../rpa/doc/rpa_dbex.txt \
                          ../../rpa/doc/introduction.txt 
+
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          =
 RECURSIVE              = NO
index 2019f40..d2a19fe 100644 (file)
@@ -1,4 +1,5 @@
-/*! \page intro Introduction
+
+/** \page intro Introduction
 Regular Pattern Analyzer (RPA) is a bottom-up, recursive parser. 
 The input grammar notation is Backus–Naur Form (BNF) and the produced output is a browsable Abstract Syntax Tree (AST).
 The grammar allows Regular Expressions, so the parser can also be used as RegEx or search engine. The execution
index 4dfff9f..c7fc8f5 100644 (file)
@@ -1,3 +1,11 @@
-/*! \mainpage RPA Users Manual
-- \subpage intro "Introduction"
+
+
+/** 
+@mainpage Rpa/Tk Documentation
+- @subpage rpatk_build
+- @subpage rpa_main "Regular Pattern Analyzer"
+       - @subpage rpa_intro
+       - @subpage rpa_bnf      
+       - @subpage rpa_dbex
 */
+
diff --git a/rpa/doc/rpa_bnf.txt b/rpa/doc/rpa_bnf.txt
new file mode 100644 (file)
index 0000000..0e95a4f
--- /dev/null
@@ -0,0 +1,3 @@
+/** \page rpa_bnf BNF Syntax.
+
+*/
diff --git a/rpa/doc/rpa_dbex.txt b/rpa/doc/rpa_dbex.txt
new file mode 100644 (file)
index 0000000..6083820
--- /dev/null
@@ -0,0 +1,11 @@
+/** \page rpa_dbex Loading and compiling BNF productions.
+To use a BNF schema for parsing, searching or matching you must first load and
+compile the BNF schema using the @ref rpadbex_t API.
+
+- 1. Create an BNF expression database (rpadbex_t object), using @ref rpa_dbex_create.
+- 2. Open the expression database, using @ref rpa_dbex_open.
+- 3. Load the BNF productions into the databse, using @ref rpa_dbex_load or @ref rpa_dbex_load_s.
+- 4. Close the database, using @ref rpa_dbex_close.
+- 5. Compile the BNF productions in the database to byte code, using @ref rpa_dbex_compile.
+
+*/
\ No newline at end of file
diff --git a/rpa/doc/rpa_intro.txt b/rpa/doc/rpa_intro.txt
new file mode 100644 (file)
index 0000000..f425fae
--- /dev/null
@@ -0,0 +1,37 @@
+/** \page rpa_intro Introduction
+Regular Pattern Analyzer (RPA) is a bottom-up, recursive parser. 
+The input grammar notation is Backus–Naur Form (BNF) and the produced output is a browsable Abstract Syntax Tree (AST).
+The grammar allows Regular Expressions, so the parser can also be used as RegEx or search engine. The execution
+engine supports muti-threading and it can parse multiple input streams simultaneously.
+
+\section features Features
+ - Backus–Naur Form (BNF)
+
+ - Produces a browsable Abstract Syntax Tree
+ - Regular Expressions
+ - Input Encodings: UTF8, UTF16
+ - Case sensitive/insensitive searching or parsing
+ - Left-Recursive expressions (direct and indirect)
+
+ - Right-Recursive expressions (direct and indirect)
+
+ - Multi-Threading.
+
+Support for recursive expressions is important for parsing computer languages, especially the Left-Recursion.
+The RPA parser is capable to handle both direct and indirect left and right recursive expressions.
+It uses iterative algorithm to handle Left-Recursion, because it is impossible to handle Left-Recursive expressions using recursion.  
+Left-Recursive expressions produce left associativity and that is what you would want to use for parsing mathematical expressions. Math operations normally 
+have left associativity. For example, consider the expression 7 − 4 + 2. The result could be either (7 − 4) + 2 = 5 or 7 − (4 + 2) = 1. 
+The former result corresponds to the case when + and − are left-associative, the latter to when + and - are right-associative.
+
+\section design Design
+RPA analyzes the BNF schema and builds a parsing tree. Then the parsing tree is compiled to byte code. The byte code is run in a
+virtual machine to parse the input stream and produce an Abstract Syntax Tree (AST). Once the schema is compiled to byte code, the
+code can be run in multiple VMs (threads), the parser naturally supports multi-threading. 
+
+
+*/
diff --git a/rpa/doc/rpa_main.txt b/rpa/doc/rpa_main.txt
new file mode 100644 (file)
index 0000000..e909296
--- /dev/null
@@ -0,0 +1,4 @@
+/** \page rpa_main "Regular Pattern Analyzer (RPA)"
+Regular Pattern Analyzer (RPA) is a bottom-up, recursive parser. 
+
+*/
\ No newline at end of file
diff --git a/rpa/doc/rpatk_build.txt b/rpa/doc/rpatk_build.txt
new file mode 100644 (file)
index 0000000..c51cc1a
--- /dev/null
@@ -0,0 +1,45 @@
+/** @page rpatk_build Build from source
+
+<h2>Linux</h2>
+To build the source tree and install on Linux:
+@code
+# cd rpatk/build/linux/ARCH_DIR
+# make BLDCFG=release
+# sudo make install
+@endcode
+
+Add the path to Rpa/Tk headers:
+@code
+-I/usr/include/rpatk
+@endcode
+
+To link to the Rpa/Tk libraries on Linux add the following link options:
+@code
+-lrpa -lrvm -lrlib -lm
+@endcode
+
+RVM library uses some math functions from the system math library, 
+that is why you must include '-lm' to include the math library to your project
+in addition to the Rpa/Tk built libraries:
+- librpa
+- librvm
+- librlib
+
+To build the PHP extension prpa.so on Linux:
+@code
+# cd rpatk/phpext/prpa
+# phpize
+# ./configure
+# make
+# sudo make install
+@endcode
+
+Add the prpa.so PHP extension to your php.ini
+
+@code
+extension=prpa.so
+@endcode
+
+
+*/
index 324b6e1..5a02c91 100644 (file)
  */
 
 /**
+ * @addtogroup rpa Regular Pattern Analyser (RPA)
+ * @{
+ *
+ */
+
+/**
  * \file rpa/rpadbex.h
  * \brief The public interface to BNF productions database API
  *
- *
  * <h2>Synopsis</h2>
  * The following APIs are used to Create, Compile, Enumerate, etc. BNF productions.
  *
@@ -410,6 +415,10 @@ rinteger rpa_dbex_dumpuids(rpadbex_t *dbex);
  * \example personname.c
  */
 
+/**
+ * @}
+ */
+
 
 #ifdef __cplusplus
 }