From b48a0785100c3da24f804fd6868e7876b0fb576b Mon Sep 17 00:00:00 2001
From: ian <ian>
Date: Sun, 27 Mar 2005 22:40:16 +0000
Subject: [PATCH] better documentation xrefs.  invent info_nfoobars

---
 layout/data2safety   |  3 ++-
 layout/informat.txt  |  7 +++++++
 layout/layout-data.h | 22 ++++++++++++++++++++--
 layout/redactgraph.c |  3 +++
 4 files changed, 32 insertions(+), 3 deletions(-)

diff --git a/layout/data2safety b/layout/data2safety
index c7cefc2..b848848 100755
--- a/layout/data2safety
+++ b/layout/data2safety
@@ -274,7 +274,8 @@ sub writeout () {
 	}
 	o("\n};\n");
     }
-    o("static const SegmentInfo info_segments[".scalar(@segs)."]= {");
+    o("const SegmentNum info_nsegments=NUM_SEGMENTS;\n");
+    o("const SegmentInfo info_segments[NUM_SEGMENTS]= {");
     $delim= '';
     foreach $seg (@segs) {
 	$segr= $segs{$seg};
diff --git a/layout/informat.txt b/layout/informat.txt
index 15be4ee..9a4cab7 100644
--- a/layout/informat.txt
+++ b/layout/informat.txt
@@ -306,3 +306,10 @@ Special comments in PostScript:
    O!    when defining object or part O
    N:T   scope T but inside part (introduced with `part') N      } when
    O::T  scope T but inside obj (introduced with `obj[flip]') O  } placing
+
+
+See also:
+ layout-data.h for info regarding layout data deliverables for use by
+                 control and UI software
+ redactgraph.c, extractgraph for info regarding extraction and
+                  preparation of those deliverables
diff --git a/layout/layout-data.h b/layout/layout-data.h
index 2d1eed3..4d287d6 100644
--- a/layout/layout-data.h
+++ b/layout/layout-data.h
@@ -1,4 +1,13 @@
-/**/
+/*
+ */
+/* The output from the layout processing system to the control
+ * software, describing the layout and the trains, is a data structure
+ * as described in this header file, in <name-of-layout>.layout-data.o
+ * (where <name-of-layout> is currently `ours').
+ *
+ * Alternatively, <name-of-layout>.redacted.forsafety contains data in
+ * the form described at the top of redactgraph.c.
+ */
 
 #ifndef LAYOUT_DATA_H
 #define LAYOUT_DATA_H
@@ -47,7 +56,16 @@ typedef struct {
   const char *pname;
 } TrainInfo;
 
-extern const SegmentInfo info_segments[];
+/* These data arrays have no sentinel members.  Use the info_nfoobars
+ * constants.  Alternatively, it is legal to sed out everything from
+ * <name-of-layout>.layout-data.c from the first #include onwards, and
+ * this will give definitions of NUM_SEGMENTS and NUM_TRAINS.
+ */
+
+extern const SegmentNum info_nsegments;
+extern const SegmentInfo info_segments[]; 
+
+extern const TrainNum info_nsegments;
 extern const TrainInfo info_trains[];
 
 #define NOTA(x) (~(x##Num)0)
diff --git a/layout/redactgraph.c b/layout/redactgraph.c
index 7dcb743..9900e7e 100644
--- a/layout/redactgraph.c
+++ b/layout/redactgraph.c
@@ -22,6 +22,9 @@
  *      the same <segment>
  *    - not at all (indicates a terminus)
  * Refer to safety.h for info regarding <combpos>.
+ *
+ * See layout-data.h comment for info regarding layout data for
+ * control system.
  */
 /* for debugging, runes like
  *  ./ours.redactgraph consistency movfeatsplitedges consistency movfeatrmstubs consistency movfeatsplitnodes consistency trivpairnodes consistency trivnullnodes consistency printforneato | neato -Tps >u.ps
-- 
2.30.2