diff --git a/README.md b/README.md
index 80cb69b..5748a07 100644
--- a/README.md
+++ b/README.md
@@ -3,4 +3,8 @@ Jonathan's Literate Programming
 
 This project grew out of a desire for a documentation system that:
 
-* 
+* generates all documentation from source-code comments,
+* is capable of facilitating both JavaDoc-style API documentation as well as
+  literate programming style of documentation,
+* has pluggable formatting (default to Markdown),
+
diff --git a/doc/grammar.rst b/doc/grammar.rst
index b1021a4..bbf532e 100644
--- a/doc/grammar.rst
+++ b/doc/grammar.rst
@@ -1,9 +1,25 @@
-DocBlock -> Directive | MarkdownBlock
+CodePage -> CodeBlock | DocBlock | CodePage
 
-Directive ->
-    "@author" MarkdownBlock |
-    "@doc" MarkdownBlock |
-    "@example" MarkdownBlock |
-    "@org" LiteralString
+// lookahead 2 needed here
+DocBlock -> DirectiveBlock | MarkdownBlock | DocBlock
 
-MarkdownBlock ->
+DirectiveBlock ->
+    <DOC_START> <DIRECTIVE_START> "author" RemainingLine EOL MarkdownBlock? |
+    <DOC_START> <DIRECTIVE_START> "doc" RemainingLine EOL MarkdownBlock? |
+    <DOC_START> <DIRECTIVE_START> "example" RemainingLine EOL MarkdownBlock? |
+    <DOC_START> <DIRECTIVE_START> "org" OrgString EOL
+
+MarkdownBlock -> MarkdownLine+
+
+MarkdownLine ->
+    <DOC_START> NOT_DIRECTIVE_START RemainingLine <EOL>
+
+RemainingLine -> NOT_EOL*
+Tokens
+------
+
+DOC_START -> "%%"
+EOL       -> "\n"
+NOT_EOL   -> ~"\n"
+DIRECTIVE_START -> "@"
+NOT_DIRECTIVE_START -> ~"@"