docs/snc: check syntax productions in the reference for consistency

We no longer include the syntax summary generated from the parser input
file in the reference. This was unreadable anyway. Instead, check that
the syntax productions in the reference are consistent with the
generated ones and complain during build if that is not the case.

Along the way, renamed the generated file from bnf.inc to Syntax.txt and
install it into the html install location; also renamed about.inc to
About.txt, adding both to unused_docs in the sphinx configuration.

.boring

@@ -122,7 +122,6 @@
 ^html($|/)
 
 ### Sequencer
-^documentation/bnf.inc$
 ^seq\.
 # darcs patches received or created locally
 ^.*\.dpatch$

Makefile

@@ -31,7 +31,7 @@ docs: src
 docs.clean:
 	$(MAKE) -C documentation clean
 
-clean: docs.clean
+realclean clean: docs.clean
 
 upload_docs: docs
 	rsync -r -t $(TOP)/html/ $(USER_AT_HOST):$(SEQ_PATH)/

documentation/Introduction.txt

@@ -4,7 +4,7 @@ Introduction
 About
 -----
 
-.. include:: about.inc
+.. include:: About.txt
 
 .. _Overview:
 

documentation/Makefile

@@ -14,7 +14,7 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
 .PHONY: install all build realclean
 .PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes
-.PHONY: linkcheck doctest
+.PHONY: linkcheck doctest checksyntax
 
 install all: build
 	cp -r $(BUILDDIR)/html $(INSTALL_LOCATION)
@@ -22,7 +22,7 @@ ifdef pdf
 	cp $(BUILDDIR)/latex/Manual.pdf $(INSTALL_LOCATION)/html
 endif
 
-build: html
+build: html checksyntax
 
 ifdef pdf
 build: pdf
@@ -46,11 +46,16 @@ realclean clean:
 
 runtests:
 
-html: bnf.inc
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+checksyntax: html extractbnf.pl Reference.txt $(INSTALL_LOCATION)/html/Syntax.txt
+	sort $(INSTALL_LOCATION)/html/Syntax.txt > $(BUILDDIR)/Syntax.txt.sorted.tmp
+	$(MV) $(BUILDDIR)/Syntax.txt.sorted.tmp $(BUILDDIR)/Syntax.txt.sorted
+	$(PERL) extractbnf.pl Reference.txt | sort > $(BUILDDIR)/Reference.txt.sorted.tmp
+	$(MV) $(BUILDDIR)/Reference.txt.sorted.tmp $(BUILDDIR)/Reference.txt.sorted
+	if ! diff $(BUILDDIR)/Syntax.txt.sorted $(BUILDDIR)/Reference.txt.sorted; then\
+		echo "warning: syntax is inconsistent with specification"; fi
 
-# 	@echo
-# 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml

documentation/Reference.txt

@@ -2398,13 +2398,3 @@ variable, and then does a pvPut::
            } state doit
        }
    }
-
-
-Syntax Summary
---------------
-
-What follows is a summary of all syntax rules. It is guaranteed to be
-up-to-date as it is automatically generated from the parser generator
-specification.
-
-.. include:: bnf.inc

documentation/conf.py

@@ -72,7 +72,7 @@ release = get_seq_release()
 #today_fmt = '%B %d, %Y'
 
 # List of documents that shouldn't be included in the build.
-#unused_docs = []
+unused_docs = ['Syntax', 'About']
 
 # List of directories, relative to source directory, that shouldn't be searched
 # for source files.

documentation/extractbnf.pl

+my $in_prod_list = 0;
+my $after_program_section_header = 0;
+print ".. productionlist::\n";
+while(<>) {
+  if (m/^Program$/) {
+    $after_program_section_header = 1;
+  }
+  elsif ($after_program_section_header) {
+    if (m/^.. productionlist::$/) {
+      $in_prod_list = 1;
+    }
+    elsif ($in_prod_list) {
+      if (m/^\s*$/) {
+        $in_prod_list = 0;
+      }
+      else {
+        print;
+      }
+    }
+  }
+}

documentation/index.txt

@@ -10,7 +10,7 @@ State Notation Language and Sequencer
 Welcome to the home page of the **EPICS Sequencer** project.
 
 
-.. include:: about.inc
+.. include:: About.txt
 
 .. toctree::
    :hidden:

src/snc/Makefile

@@ -29,8 +29,7 @@ snc_SRCS += builtin.c       # builtin constants and functions
 snc_LIBS += Com seq
 
 # locally overwrite default value for this variable
-INSTALL_DOC = $(INSTALL_LOCATION)/documentation
-DOCS += bnf.inc
+HTMLS += Syntax.txt
 
 include $(TOP)/configure/RULES
 #----------------------------------------
@@ -38,6 +37,7 @@ include $(TOP)/configure/RULES
 
 vpath %.lem ..
 vpath %.lt ..
+vpath %.txt $(COMMON_DIR)
 
 # this extra dependency needed for 3.14.8 compatibility
 lexer.o: snl.h
@@ -59,12 +59,9 @@ endif
 $(COMMON_DIR)/snl.bnf: snl.lem
 	$(LEMON) o=. -g $< > $@
 
-$(COMMON_DIR)/bnf.inc: ../bnf2txt.pl snl.re $(COMMON_DIR)/snl.bnf
+$(COMMON_DIR)/Syntax.txt: ../bnf2txt.pl snl.re $(COMMON_DIR)/snl.bnf
 	$(PERL) $^ > $@
 
-$(INSTALL_DOC)/%: $(COMMON_DIR)/%
-	$(INSTALL) -d -m 644 $< $(INSTALL_DOC)
-
 ifdef BASE_3_14
 %$(DEP): %.c
 	@-$(MKMF) $(HDEPENDS_FLAGS) -m $*$(DEP) $(HDEPENDS_INCLUDES) $*$(OBJ) $<