Syntax: Statements and expressions

lib/Language/syntax.pod

@@ -128,18 +128,38 @@ of comment
 say 'code again';
 =end code
 
+=head1 Statements and Expressions
+
+Perl 6 programs are made of lists of statements. A special case of a statement
+is an I<expression>, which returns a value. For example C<if True { say 42 }>
+is syntactically a statement, but not an expression, whereas C<1 + 2> is an
+expression (and thus also a statement).
+
+The C<do> prefix turns statements into expressions. So while
+
+    my $x = if True { 42 };     # Syntax error!
+
+is an error,
+
+   my $x = do if True { 42; };
+
+assign the return value of the if statement (here C<42>) to the variable
+C<$x>.
+
 =begin comment
 
-=head1 Statements and Expressions
+=head1 Terms
 
 TODO
 
-=head1 Terms
+=head3 Variables
 
 TODO
 
 =head2 Literals
 
+TODO
+
 =head3 String literals
 
 TODO: link to quotes
@@ -164,6 +184,10 @@ TODO
 
 TODO
 
+=head2 Subroutine calls
+
+TODO
+
 =head1 Operators
 
 TODO: link to language/operators