Add bare-bones syntax document

so far covering only some lexical conventions and comments

lib/Language/syntax.pod

@@ -0,0 +1,175 @@
+=begin pod
+
+=TITLE Syntax
+
+=SUBTITLE General rules of Perl 6 syntax
+
+Perl 6 borrows many concepts from human language. Which is not surprising,
+considering it was designed by a linguist.
+
+It reuses common elements in different contexts, has the notion of nouns
+(terms) and verbs (operators), is context-sensitive (in the every day sense, not
+necessarily in the Computer Science interpretation), so a symbol can have a
+different meaning depending on whether a noun or a verb is expected.
+
+It is also self-clocking, so that the parser can detect most of the common
+errors and give good error messages.
+
+=head1 Lexical Conventions
+
+Perl 6 code is Unicode text, current implementations support UTF-8 as the
+input encoding.
+
+=head2 Free Form
+
+It is free-form, in the sense that you are mostly free to
+chose the amount of whitespace you chose, though in some cases, the presence
+or absensce of whitespace carries meaning.
+
+So you can write
+
+=begin code
+if True {
+    say "Hello";
+}
+=end code
+
+or
+
+=begin code
+    if True {
+say "Hello";
+        }
+=end code
+
+or
+
+=begin code
+if True { say "Hello" }
+=end code
+
+or even
+
+=begin code
+if True {say "Hello"}
+=end code
+
+though you can't leave out any of the remaining whitespace.
+
+=head2 Separating Statements
+
+A Perl 6 program is a list of statements, separated by semicolons C<;>.
+A semicolon after the final statement (or after the final statement inside a
+block) is optional, though it's good form to include it.
+
+A closing curling brace followed by a newline character implies a statement
+separator, which is why you don't need to write a semicolon before the last
+line in the code
+
+=begin code
+if True {
+    say "Hello";
+}
+say "world";
+=end code
+
+Both semicolons are optional here, but leaving them out increases the chance
+of syntax errors when adding more lines laste.
+
+=head2 Comments
+
+Comments are parts of the program text only intended for human readers, and
+the Perl 6 compilers does not evaluate them as program text.
+
+Comments count as whitespace in places where the absence of presence of
+whitespace disambiguates possible parses.
+
+=head3 Single-line comments
+
+The most common form of comments in Perl 6 starts with a single hash character
+C<#> and goes until the end of the line.
+
+=begin code
+
+if $age > 250 {     # catch obvious outliers
+    # this is another comment!
+    die "That doesn't look right"
+}
+=end code
+
+=head3 Embedded comments
+
+Embedded comments start with a hash character, followed by a backticket, and
+then some opening bracketing character, and end with the matching closing
+bracketing character.
+
+    if #^( why would I ever write an inline comment here? ) True {
+        say "something stupid";
+    }
+
+Brackets inside the comment can be nested, so in C<#^{ a { b } c }>, the
+comment goes until the very end of the string.
+
+=head3 Multiline comments
+
+Pod syntax can be used for multi-line comments
+
+=begin code
+say "this is code";
+
+=begin comment
+
+Here are several
+lines
+of comment
+
+=end comment
+
+say 'code again';
+=end code
+
+=begin comment
+
+=head1 Statements and Expressions
+
+TODO
+
+=head1 Terms
+
+TODO
+
+=head2 Literals
+
+=head3 String literals
+
+TODO: link to quotes
+
+=head3 Number literals
+
+TODO
+
+=head3 Pair literals
+
+TODO
+
+=head3 Array literals
+
+TODO
+
+=head3 Hash literals
+
+TODO
+
+=head2 Declarations
+
+TODO
+
+=head1 Operators
+
+TODO: link to language/operators
+
+=head1 
+
+=end comment
+
+=end pod