From b07cc00facf9d44f590fa9b2ef5b2b6ab9b08911 Mon Sep 17 00:00:00 2001
From: Ben Pfaff <blp@cs.stanford.edu>
Date: Fri, 7 Aug 2015 01:13:21 -0700
Subject: [PATCH] Document all the elements, plus the attributes of heading.

---
 parse-all-xml        | 10 +++---
 parse-xml.c          | 17 ++++++++-
 spv-file-format.texi | 84 +++++++++++++++++++++++++++++++++++++++++++-
 3 files changed, 104 insertions(+), 7 deletions(-)

diff --git a/parse-all-xml b/parse-all-xml
index a91f68eab6..dbd71d596b 100755
--- a/parse-all-xml
+++ b/parse-all-xml
@@ -13,10 +13,10 @@ done | sort | uniq -c | sort -rn
 
 printf '\nAttributes:\n'
 for d in $lightTables; do
-    ./parse-xml $d attributes
+    ./parse-xml $d attr:lockReader
 done | sort | uniq -c | sort -rn
 
-printf '\nLabels:\n'
-for d in $lightTables; do
-    ./parse-xml $d labels
-done | sort | uniq -c | sort -rn
+#printf '\nLabels:\n'
+#for d in $lightTables; do
+#    ./parse-xml $d labels
+#done | sort | uniq -c | sort -rn
diff --git a/parse-xml.c b/parse-xml.c
index 85fbaf05fe..ad1b41833d 100644
--- a/parse-xml.c
+++ b/parse-xml.c
@@ -67,7 +67,7 @@ print_attributes (xmlNode * a_node)
 {
   for (xmlNode *node = a_node; node; node = node->next)
     {
-      if (node->properties)
+      if (node->properties && node->parent->type != XML_DOCUMENT_NODE)
         {
           printf ("%s", node->name);
           for (xmlAttr *attr = node->properties; attr; attr = attr->next)
@@ -79,6 +79,19 @@ print_attributes (xmlNode * a_node)
     }
 }
 
+static void
+print_attribute (xmlNode *node, const char *attr)
+{
+  for (; node; node = node->next)
+    {
+      const char *s = (char *) xmlGetProp (node, (xmlChar *) attr);
+      if (s)
+        puts (s);
+
+      print_attribute (node->children, attr);
+    }
+}
+
 static void
 usage (void)
 {
@@ -107,6 +120,8 @@ main (int argc, char **argv)
     print_containment (root);
   else if (!strcmp(argv[2], "attributes"))
     print_attributes (root);
+  else if (!strncmp(argv[2], "attr:", 5))
+    print_attribute (root, argv[2] + 5);
   else if (!strcmp(argv[2], "labels"))
     print_labels (root);
   else
diff --git a/spv-file-format.texi b/spv-file-format.texi
index 1497c49b6d..987a06dcf8 100644
--- a/spv-file-format.texi
+++ b/spv-file-format.texi
@@ -100,6 +100,67 @@ section of output beginning with a title (the @code{label}) and
 ordinarily followed by a container for content and possibly further
 nested (sub)-sections of output.
 
+The following attributes have been observed on both document root and
+nested @code{heading} elements:
+
+@table @asis
+@item Optional attribute: @code{creator-version}
+The version of the software that created this SPV file.  A string of
+the form @code{xxyyzzww} represents software version xx.yy.zz.ww,
+e.g.@: @code{21000001} is version 21.0.0.1.  Trailing pairs of zeros
+are sometimes omitted, so that @code{21}, @code{210000}, and
+@code{21000000} are all version 21.0.0.0 (and the corpus contains all
+three of those forms).
+@end table
+
+The following attributes have been observed on document root
+@code{heading} elements only:
+
+@table @asis
+@item Optional attribute: @code{creator}
+The directory of the software that created this SPV file,
+e.g. @file{C:\PROGRA~1\IBM\SPSS\STATIS~1\22} or
+@file{/Applications/IBM/SPSS/Statistics/22/SPSSStatistics.app/Contents/Resources/Java/../../bin}.
+
+@item Optional attribute: @code{creation-date-time}
+The date and time at which the SPV file was written, in a
+locale-specific format, e.g. @code{Friday, May 16, 2014 6:47:37 PM
+PDT} or @code{lunedì 17 marzo 2014 3.15.48 CET} or even @code{Friday,
+December 5, 2014 5:00:19 o'clock PM EST}.
+
+@item Optional attribute: @code{lockReader}
+Whether a reader should be allowed to edit the output.  The possible
+values are @code{true} and @code{false}, but the corpus only contains
+@code{false}.
+
+@item Optional attribute: @code{schemaLocation}
+This is actually an XML Namespace attribute.  A reader may ignore it.
+@end table
+
+The following attributes have been observed only on nested
+@code{heading} elements:
+
+@table @asis
+@item Required attribute: @code{commandName}
+The locale-invariant name of the command that produced the output,
+e.g.@: @code{Frequencies} or @code{T-Test}.  For output not specific
+to a command, this is simply @code{log}.
+
+@item Optional attribute: @code{visibility}
+To what degree the output represented by the element is visible.  The
+possible values are @code{visible}, @code{hidden}, and
+@code{collapsed}.
+
+@item Optional attribute: @code{locale}
+The locale used for output, in Windows format, which is similar to the
+format used in Unix with the underscore replaced by a hyphen, e.g.@:
+@code{en-US}, @code{en-GB}, @code{el-GR}, @code{sr-Cryl-RS}.
+
+@item Optional attribute: @code{olang}
+The output language, e.g.@: @code{en}, @code{it}, @code{es},
+@code{de}, @code{pt-BR}.
+@end table
+
 @item label
 Parent: @code{heading} or @code{container} @*
 Contents: text
@@ -121,5 +182,26 @@ no text.
 Parent: @code{heading} @*
 Contents: @code{label} [@code{table} | @code{text}]
 
-A @code{container} is the immediate parent of a 
+A @code{container} serves to label a @code{table} or a @code{text}
+item.
+
+@item text
+Parent: @code{container} @*
+Contents: @code{html}
+
+@item html
+Parent: @code{text} @*
+Contents: cdata
+
+@item table
+Parent: @code{container} @*
+Contents: @code{tableStructure}
+
+@item tableStructure
+Parent: @code{table}
+Contents: @code{dataPath}
+
+@item dataPath
+Parent: @code{tableStructure}
+Contents: text
 @end table
-- 
2.30.2