better documentation xrefs. invent info_nfoobars

diff --git a/layout/data2safety b/layout/data2safety
index c7cefc24ba6db212e6c38bab031134514d075901..b8488487452af2b19cf32b8ac8c07d00a3d44b4a 100755 (executable)
--- 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 15be4eee5e72864594d3f8f96e0628fc76f22456..9a4cab79dbd0c7190cc036a3454657fe1f660269 100644 (file)
--- 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 2d1eed3cd656e82a49b78b4d67f800ad187f879f..4d287d6ebe9d0338703613835d15d4a8b29b84bd 100644 (file)
--- 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 7dcb7439ebee0de3a2264c2b6ab5800773efe94d..9900e7edeccd82788b7c9ed4488eadc8346435b4 100644 (file)
--- 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