From 278b54227339099faf93301cfd4a6b566651441b Mon Sep 17 00:00:00 2001
From: Robert Baruch <robert.c.baruch@gmail.com>
Date: Tue, 24 Nov 2020 15:27:30 -0800
Subject: [PATCH] Cleans up some descriptions and syntax

Now all rules ending in "-stmt" end in eol.
---
 manual/CHAPTER_TextRtlil.tex | 68 +++++++++++++++++++++++-------------
 1 file changed, 43 insertions(+), 25 deletions(-)

diff --git a/manual/CHAPTER_TextRtlil.tex b/manual/CHAPTER_TextRtlil.tex
index e84235398..720fe8fa1 100644
--- a/manual/CHAPTER_TextRtlil.tex
+++ b/manual/CHAPTER_TextRtlil.tex
@@ -87,33 +87,35 @@ A comment starts with a \texttt{\textbf{\#}} character and proceeds to the end o
 
 \section{File}
 
-A file consists of zero or more designs. A design may be a module, an attribute statement, or an autoindex statement.
+A file consists of zero or more modules, attribute statements, and auto-index statements. All statements terminate in an end-of-line. Because of this, statements cannot contain end-of-lines.
 
-Note that in general, statements are terminated by an end of line.
+Attributes at the file level are applied to the following module.
 
 \begin{indentgrammar}{<design>}
-<file> ::= <design>$*$
-
-<design> ::= <module> | <attr-stmt> | <autoidx-stmt>
+<file> ::= (<module> | <attr-stmt> | <autoidx-stmt>)$*$
 \end{indentgrammar}
 
 \subsection{Modules}
 
-A module consists of zero or more module statements.
+Declares a module consisting of zero or more attributes, wires, memories, cells, processes, and connections.
+
+\begin{indentgrammar}{<module-body-stmt>}
+<module> ::= <module-stmt> <module-body> <module-end-stmt>
 
-\begin{indentgrammar}{<module-stmt>}
-<module> ::= "module" <id> <eol> <module-stmt>$*$ "end" <eol>
+<module-stmt> ::= "module" <id> <eol>
 
-<module-stmt> ::= 
-<param-stmt>
+<module-body> ::= 
+(<param-stmt>
   \alt <attr-stmt>
   \alt <wire-stmt>
   \alt <memory-stmt>
-  \alt <cell-stmt>
-  \alt <proc-stmt>
-  \alt <conn-stmt>
+  \alt <cell>
+  \alt <process>
+  \alt <conn-stmt>)$*$
 \end{indentgrammar}
 
+<module-end-stmt> ::= "end" <eol>
+
 \subsection{Signal specifications}
 
 A signal is anything that can be applied to a cell port, i.e. a constant value, all bits or a selection of bits from a wire, or concatenations of those.
@@ -138,7 +140,7 @@ Declares a connection between the given signals.
 
 \subsection{Attribute statements}
 
-Declares an attribute with the given identifier and value for the following non-attribute statement.
+Declares an attribute with the given identifier and value. Attributes at the file level apply to the following module. Attributes within a module apply to the following non-attribute statement.
 
 \begin{indentgrammar}{<attr-stmt>}
 <attr-stmt> ::= "attribute" <id> <constant> <eol>
@@ -198,14 +200,16 @@ See Sec.~\ref{sec:rtlil_memory} for an overview of memory cells, and Sec.~\ref{s
   \alt "offset" <integer>
 \end{indentgrammar}
 
-\subsection{Cell statements}
+\subsection{Cells}
 
 Declares a cell with the given identifier in the enclosing module.
 
 See Chap.~\ref{chapter:celllib} for a detailed list of cell types.
 
 \begin{indentgrammar}{<cell-body-stmt>}
-<cell-stmt> ::= "cell" <cell-id> <cell-type> <eol> <cell-body-stmt> "end" <eol>
+<cell> ::= <cell-stmt> <cell-body-stmt> <cell-end-stmt>
+
+<cell-stmt> ::= "cell" <cell-id> <cell-type> <eol>
 
 <cell-id> ::= <id>
 
@@ -214,6 +218,8 @@ See Chap.~\ref{chapter:celllib} for a detailed list of cell types.
 <cell-body-stmt> ::= 
 "parameter" ("signed" | "real")$?$ <id> <constant> <eol>
   \alt "connect" <id> <sigspec> <eol>
+
+<cell-end-stmt> ::= "end" <eol>
 \end{indentgrammar}
 
 \subsection{Process statements}
@@ -222,22 +228,34 @@ Declares a process with the given identifier in the enclosing module.
 
 See Sec.~\ref{sec:rtlil_process} for an overview of processes.
 
-\begin{indentgrammar}{<switch-element>}
-<proc-stmt> ::= "process" <id> <eol> <case-stmt>$*$ <sync-stmt>$*$ "end" <eol>
+\begin{indentgrammar}{<switch-end-stmt>}
+<process> ::= <proc-stmt> <case-body> <sync>$*$ <proc-end-stmt>
+
+<proc-stmt> ::= "process" <id> <eol>
 
-<case-stmt> ::= <attr-stmt> | <switch-stmt> | <assign-stmt>
+<proc-end-stmt> ::= "end" <eol>
 
-<switch-stmt> ::= "switch" <sigspec> <eol> <attr-stmt>$*$ <switch-element>$*$ "end" <eol>
+<case-body> ::= (<attr-stmt> | <switch> | <assign-stmt>)$*$
 
-<switch-element> ::= "case" <compare>$?$ <eol> <case-stmt>$*$
+<switch> ::= <switch-stmt> <attr-stmt>$*$ <case>$*$ <switch-end-stmt>
+
+<switch-stmt> := "switch" <sigspec> <eol>
+
+<switch-end-stmt> ::= "end" <eol>
+
+<case> ::= <case-stmt> <case-body>
+
+<case-stmt> ::= "case" <compare>$?$ <eol>
 
 <compare> ::= <sigspec> ("," <sigspec>)$*$
 
+<sync> ::= <sync-stmt> <update-stmt>$*$
+
 <sync-stmt> ::= 
-"sync" <sync-type> <sigspec> <eol> <update-stmt>$*$
-  \alt "sync" "always" <eol> <update-stmt>$*$
-  \alt "sync" "global" <eol> <update-stmt>$*$
-  \alt "sync" "init" <eol> <update-stmt>$*$
+"sync" <sync-type> <sigspec> <eol>
+  \alt "sync" "always" <eol>
+  \alt "sync" "global" <eol>
+  \alt "sync" "init" <eol>
 
 <sync-type> ::= "low" | "high" | "posedge" | "negedge" | "edge"
 
-- 
2.30.2