From d46de3ea86d1c1fede8966e9345fc0455c5a9092 Mon Sep 17 00:00:00 2001
From: Hugues Delorme <delorme.hugues@fougsys.fr>
Date: Mon, 29 Apr 2013 12:24:51 +0200
Subject: [PATCH] stla: document grammar for STL ASCII

---
 src/c/libstl/stla_read.c | 46 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/src/c/libstl/stla_read.c b/src/c/libstl/stla_read.c
index 3210a8b..7480027 100644
--- a/src/c/libstl/stla_read.c
+++ b/src/c/libstl/stla_read.c
@@ -7,6 +7,52 @@
 #include <stdlib.h>
 #include <string.h>
 
+/*
+ *
+ * STL ASCII grammar:
+ *
+ *  \code
+
+    CONTENTS  -> SOLID
+    CONTENTS  -> SOLID  SOLID
+
+    SOLID     -> BEG_SOLID  FACETS  END_SOLID
+    BEG_SOLID -> solid  SOLID_NAME
+    END_SOLID -> endsolid SOLID_NAME
+
+    SOLID_NAME ->
+    SOLID_NAME -> [id]  (Note: [id] == facet is forbidden)
+
+    FACETS ->
+    FACETS -> F
+    FACETS -> FF
+    F      -> facet N outer loop V V V endloop endfacet
+
+    V   -> vertex XYZ
+    N   -> normal XYZ
+    XYZ -> [float] [float] [float]
+
+ *  \endcode
+ *
+ *  Nullable, FIRST and FOLLOW:
+ *  \code
+                | Nullable |     FIRST    |           FOLLOW
+      ----------+----------+--------------µ-----------------------------
+       CONTENTS |    N           solid
+          SOLID |    N           solid                 solid
+      BEG_SOLID |    N           solid                 facet
+      END_SOLID |    N          endsolid               solid
+     SOLID_NAME |    Y           [id]           facet, endsolid, solid
+         FACETS |    Y           facet
+              F |    N           facet             facet, endsolid
+              N |    N           normal                 outer
+              V |    N           vertex             vertex, endloop
+            XYZ |    N           [float]        outer, vertex, endloop
+
+ *  \endcode
+ *
+ */
+
 /* foug_stream_fwd_iterator */
 struct foug_stream_fwd_iterator
 {