From 95099d99a127e024eb275e96b3bedd5369df818b Mon Sep 17 00:00:00 2001
From: "benjamin.franksen" <benjamin.franksen@helmholtz-berlin.de>
Date: Sat, 28 Sep 2013 23:35:17 +0000
Subject: [PATCH] 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 | 1 -
Makefile | 2 +-
documentation/{about.inc => About.txt} | 0
documentation/Introduction.txt | 2 +-
documentation/Makefile | 17 +++++++++++------
documentation/Reference.txt | 10 ----------
documentation/conf.py | 2 +-
documentation/extractbnf.pl | 21 +++++++++++++++++++++
documentation/index.txt | 2 +-
src/snc/Makefile | 9 +++------
10 files changed, 39 insertions(+), 27 deletions(-)
rename documentation/{about.inc => About.txt} (100%)
create mode 100644 documentation/extractbnf.pl
diff --git a/.boring b/.boring
index bb544a18..4104d9bd 100644
--- a/.boring
+++ b/.boring
@@ -122,7 +122,6 @@
^html($|/)
### Sequencer
-^documentation/bnf.inc$
^seq\.
# darcs patches received or created locally
^.*\.dpatch$
diff --git a/Makefile b/Makefile
index b9d722c9..78a93ac3 100644
--- a/Makefile
+++ b/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)/
diff --git a/documentation/about.inc b/documentation/About.txt
similarity index 100%
rename from documentation/about.inc
rename to documentation/About.txt
diff --git a/documentation/Introduction.txt b/documentation/Introduction.txt
index ac5dc9e8..bcc6b832 100644
--- a/documentation/Introduction.txt
+++ b/documentation/Introduction.txt
@@ -4,7 +4,7 @@ Introduction
About
-----
-.. include:: about.inc
+.. include:: About.txt
.. _Overview:
diff --git a/documentation/Makefile b/documentation/Makefile
index e191e249..aca081ae 100644
--- a/documentation/Makefile
+++ b/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
diff --git a/documentation/Reference.txt b/documentation/Reference.txt
index 58eeed78..72fbd631 100644
--- a/documentation/Reference.txt
+++ b/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
diff --git a/documentation/conf.py b/documentation/conf.py
index f2e187f2..4a9ed6f4 100644
--- a/documentation/conf.py
+++ b/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.
diff --git a/documentation/extractbnf.pl b/documentation/extractbnf.pl
new file mode 100644
index 00000000..20bfaa67
--- /dev/null
+++ b/documentation/extractbnf.pl
@@ -0,0 +1,21 @@
+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;
+ }
+ }
+ }
+}
diff --git a/documentation/index.txt b/documentation/index.txt
index 77b2ab93..f1062c50 100644
--- a/documentation/index.txt
+++ b/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:
diff --git a/src/snc/Makefile b/src/snc/Makefile
index 35ec8649..39decabf 100644
--- a/src/snc/Makefile
+++ b/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) $<
--
GitLab