Add: initial README

1 files changed, 48 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..f1a9f84
--- /dev/null
+++ b/README
@@ -0,0 +1,48 @@
+README for wikitexttest
+=============================================================================
+
+wikitexttest is a RUDIMENTARY test suite for implementations of
+"wikitext", the markup language understood by MediaWiki, the wiki
+engine used by Wikipedia and other sites.
+
+This is an unofficial side project. Wikitext does not have an official
+specification, but there are several implementations and it is the
+hope that this test suite might eventually maybe possibly perhaps be
+the first step towards a minimal information specification for it that
+all interested applications can agree on.
+
+
+
+Architecture
+-----------------------------------------------------------------------------
+
+The architecture of the test suite is as follows: each test consists
+of an input file in wikitext, and the expected output as HTML. The
+test suite is provided with a wikitext implementation with a Unix
+command line program. The test suite feeds each input file to the
+program via stdin, and compares the stdout against the expected HTML.
+The comparison is done against normalised parse trees, not textually,
+to ignore irrlevant differences such amount of white space.
+
+For example, the input file might be:
+
+```
+hello '''world'''
+```
+
+The expected HTML output would be:
+
+```html
+<p>hello <b>world</b></p>
+```
+
+He wikitext implementation might instead output the following, and it
+would still be acceptable:
+
+
+```html
+<P>hello
+ <B>world</B>
+</P>
+```
+