From a5289a72246eb0130c44456284d32e8eea61df74 Mon Sep 17 00:00:00 2001
From: Matthew Parkinson <mattpark@microsoft.com>
Date: Tue, 16 Apr 2024 10:19:51 +0100
Subject: [PATCH 1/3] Move lexical section into separate file

---
 spec/lexical.md | 34 ++++++++++++++++++++++++++++++++++
 spec/spec.md    | 36 +-----------------------------------
 2 files changed, 35 insertions(+), 35 deletions(-)
 create mode 100644 spec/lexical.md

diff --git a/spec/lexical.md b/spec/lexical.md
new file mode 100644
index 000000000..43f0ce87c
--- /dev/null
+++ b/spec/lexical.md
@@ -0,0 +1,34 @@
+## Lexical Elements
+
+### Comments
+
+### Identifiers and Symbols
+
+- `_` as "don't care".
+
+### Primitive literals
+
+- Boolean
+- Various integers and floats
+
+> [TODO:] How to talk about integer literals not having a type yet?  That is, 0 is zero, not a particular type of 0.  https://www.haskell.org/tutorial/numbers.html  
+
+### Array literals
+
+### String literals
+
+> [TODO:] String literals are not for a specific text encoding, like 0 is the zero it needs to be (float, signed, unsigned, 1/2/4/8/16/32/64bit, etc.).
+
+### Lambdas
+
+### Object Literals
+
+> [Open issues:]  code reuse, possible conflict with "real" `new`.
+> Note that the parser current uses `new { ... }` as an object literal, which might conflict with object allocation.
+
+### Expression Termination
+
+- Blank lines
+- New lines
+- Indentation
+- Trailing lambdas
diff --git a/spec/spec.md b/spec/spec.md
index b27e7e954..3e6676b8a 100644
--- a/spec/spec.md
+++ b/spec/spec.md
@@ -4,41 +4,7 @@ This document is a work in progress. It is intended to be a comprehensive guide
 
 > [Notes from discussion:] Should contain "rationale subsections" to explain why things are the way they are.
 
-
-## Lexical Elements
-
-### Comments
-
-### Identifiers and Symbols
-
-- `_` as "don't care".
-
-### Primitive literals
-
-- Boolean
-- Various integers and floats
-
-> [TODO:] How to talk about integer literals not having a type yet?  That is, 0 is zero, not a particular type of 0.  https://www.haskell.org/tutorial/numbers.html  
-
-### Array literals
-
-### String literals
-
-> [TODO:] String literals are not for a specific text encoding, like 0 is the zero it needs to be (float, signed, unsigned, 1/2/4/8/16/32/64bit, etc.).
-
-### Lambdas
-
-### Object Literals
-
-> [Open issues:]  code reuse, possible conflict with "real" `new`.
-> Note that the parser current uses `new { ... }` as an object literal, which might conflict with object allocation.
-
-### Expression Termination
-
-- Blank lines
-- New lines
-- Indentation
-- Trailing lambdas
+## [Lexical Elements](lexical.md)
 
 ## Program Structure
 

From a4d206534d7ea273bb2f6c0f7e64a0b70fcfc5c5 Mon Sep 17 00:00:00 2001
From: Matthew Parkinson <mattpark@microsoft.com>
Date: Tue, 16 Apr 2024 10:27:02 +0100
Subject: [PATCH 2/3] Explain comment syntax.

---
 spec/lexical.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/spec/lexical.md b/spec/lexical.md
index 43f0ce87c..61f019f69 100644
--- a/spec/lexical.md
+++ b/spec/lexical.md
@@ -2,6 +2,45 @@
 
 ### Comments
 
+Verona supports two types of comments.
+The first type is a single line comment:
+```
+// Single line comments
+```
+These start with a `//` and continue to the end of the line.
+The termination of the comment is the end of the line or the end of file, which ever occurs sooner.
+
+The second type of comment is a block comment:
+```
+/* Block comments */
+```
+These comments begin with a `/*` and end with a `*/`.
+They can span multiple lines.
+```
+/*
+   This is a multi-
+   line block comment.
+ */
+```
+
+The block comment is nestable, meaning that you can have a block comment within a block comment.
+```
+/* Block comments can contain commented code.
+   /* This is a block comment */
+   f(x,y,z)
+   /* with another block comment */
+   g(x,y,z)
+ */
+```
+There is no limit to the nesting depth of block comments.
+
+Block comments must be correctly terminated.
+That is every `/*` must have a corresponding `*/`.
+A non-terminated block comment is a syntax error.
+
+> [TODO:] Explain interaction with string literals.
+>         Possibly, here or in string section.
+
 ### Identifiers and Symbols
 
 - `_` as "don't care".

From 179157752faaa276c74c9b68c22fd6c12deddedd Mon Sep 17 00:00:00 2001
From: Matthew Parkinson <mattpark@microsoft.com>
Date: Tue, 16 Apr 2024 10:29:24 +0100
Subject: [PATCH 3/3] Make file more self-contained.

---
 spec/lexical.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/spec/lexical.md b/spec/lexical.md
index 61f019f69..0f445d430 100644
--- a/spec/lexical.md
+++ b/spec/lexical.md
@@ -1,5 +1,9 @@
 ## Lexical Elements
 
+This section explains the lexical elements of the Verona language.
+It forms part of the [language specification](spec.md),
+which is intended to be a comprehensive guide to the Verona programming language.
+
 ### Comments
 
 Verona supports two types of comments.