Adding upstream version 18.2.2.upstream/18.2.2

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

8 files changed, 126 insertions, 0 deletions

diff --git a/src/boost/tools/docca/util/comparison/README.md b/src/boost/tools/docca/util/comparison/README.md
new file mode 100644
index 000000000..0c869e0d9
--- /dev/null
+++ b/src/boost/tools/docca/util/comparison/README.md
@@ -0,0 +1,28 @@
+# Docca comparison scripts
+
+The scripts in this directory help guard against docca regressions by
+comparing a previous doc build's output with the latest output
+(after normalizing/scrubbing the results to eliminate non-substantive
+changes).
+
+Probably the easiest thing to do is add this directory to your PATH
+(or create an alias to the two scripts herein).
+
+The normal sequence goes like this:
+
+1. Run a baseline build from inside your project's doc directory by invoking
+   *update-baseline-html.sh*
+2. Implement new feature or bug fix in docca (usually by updating XSLT)
+3. Run a comparison build from inside your project's doc directory by invoking
+   *build-and-compare.sh*
+4. Review the output (in diffs.txt) to make sure everything looks good and nothing broke
+5. Otherwise, fix the regression and try again!
+
+This utility can also be useful for examining the impacts of other changes
+(such as a Doxygen upgrade!).
+
+## Implementation details
+
+The file named *grep-expressions* is used to filter out all but the matching files
+that need scrubbing. The resulting files are passed to sed and updated *in situ* based
+on the commands in the file named *sed-commands*.
diff --git a/src/boost/tools/docca/util/comparison/build-and-compare.sh b/src/boost/tools/docca/util/comparison/build-and-compare.sh
new file mode 100755
index 000000000..182f5da9c
--- /dev/null
+++ b/src/boost/tools/docca/util/comparison/build-and-compare.sh
@@ -0,0 +1,24 @@
+# This script runs a build and compares the scrubbed/normalized
+# results against the scrubbed results of a previous build (run using
+# update-baseline-html.sh). It is primarily used to guard against
+# XSLT regressions in docca.
+
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+
+! test -d htmlPREVIOUS_SCRUBBED && echo "First run update-baseline-html.sh" && exit
+
+rm -rf html_SCRUBBED
+
+echo "Running clean build..."
+b2 clean
+b2
+
+echo "Scrubbing results and storing as html_SCRUBBED..."
+cp -r html html_SCRUBBED
+cd html_SCRUBBED
+grep -rl -f ${SCRIPT_DIR}/grep-expressions . | xargs sed -i -f ${SCRIPT_DIR}/sed-commands
+
+echo "Showing diffs from previous build (stored in diffs.txt):"
+cd ..
+diff -r htmlPREVIOUS_SCRUBBED html_SCRUBBED >diffs.txt
+cat diffs.txt
diff --git a/src/boost/tools/docca/util/comparison/compare-all.sh b/src/boost/tools/docca/util/comparison/compare-all.sh
new file mode 100755
index 000000000..1a8dbd9d9
--- /dev/null
+++ b/src/boost/tools/docca/util/comparison/compare-all.sh
@@ -0,0 +1,27 @@
+cd ~/boost/tools/docca/example
+build-and-compare.sh 2>&1 &
+
+cd ~/boost/libs/static_string/doc
+build-and-compare.sh 2>&1 &
+
+cd ~/boost/libs/url/doc
+build-and-compare.sh 2>&1 &
+
+cd ~/boost/libs/json/doc
+build-and-compare.sh 2>&1 &
+
+cd ~/boost/libs/beast/doc
+build-and-compare.sh 2>&1 &
+
+wait
+
+echo "~/boost/tools/docca/example/diffs.txt:"
+cat ~/boost/tools/docca/example/diffs.txt
+echo "~/boost/libs/static_string/doc/diffs.txt:"
+cat ~/boost/libs/static_string/doc/diffs.txt
+echo "~/boost/libs/url/doc/diffs.txt:"
+cat ~/boost/libs/url/doc/diffs.txt
+echo "~/boost/libs/json/doc/diffs.txt:"
+cat ~/boost/libs/json/doc/diffs.txt
+echo "~/boost/libs/beast/doc/diffs.txt:"
+cat ~/boost/libs/beast/doc/diffs.txt
diff --git a/src/boost/tools/docca/util/comparison/grep-expressions b/src/boost/tools/docca/util/comparison/grep-expressions
new file mode 100644
index 000000000..5b47be5f6
--- /dev/null
+++ b/src/boost/tools/docca/util/comparison/grep-expressions
@@ -0,0 +1,4 @@
+<dt id="ientry-id
+<a class="indexterm" name="id
+<a name="id
+<td align="left"><p><small>Last revised: 
diff --git a/src/boost/tools/docca/util/comparison/sed-commands b/src/boost/tools/docca/util/comparison/sed-commands
new file mode 100644
index 000000000..3e2da7bf3
--- /dev/null
+++ b/src/boost/tools/docca/util/comparison/sed-commands
@@ -0,0 +1,2 @@
+s/\(<dt id="ientry-id\|<a class="indexterm" name="id\|<a name="id\)[0-9]\+/\1/g
+s/\(<td align="left"><p><small>Last revised: \)[^<]\+/\1/g
diff --git a/src/boost/tools/docca/util/comparison/update-all-baselines.sh b/src/boost/tools/docca/util/comparison/update-all-baselines.sh
new file mode 100755
index 000000000..23928710c
--- /dev/null
+++ b/src/boost/tools/docca/util/comparison/update-all-baselines.sh
@@ -0,0 +1,16 @@
+cd ~/boost/tools/docca/example
+update-baseline-html.sh 2>&1 &
+
+cd ~/boost/libs/static_string/doc
+update-baseline-html.sh >build_output.txt 2>&1 &
+
+cd ~/boost/libs/url/doc
+update-baseline-html.sh >build_output.txt 2>&1 &
+
+cd ~/boost/libs/json/doc
+update-baseline-html.sh >build_output.txt 2>&1 &
+
+cd ~/boost/libs/beast/doc
+update-baseline-html.sh >build_output.txt 2>&1 &
+
+wait
diff --git a/src/boost/tools/docca/util/comparison/update-baseline-html.sh b/src/boost/tools/docca/util/comparison/update-baseline-html.sh
new file mode 100755
index 000000000..8306cfc9e
--- /dev/null
+++ b/src/boost/tools/docca/util/comparison/update-baseline-html.sh
@@ -0,0 +1,19 @@
+# This script runs a new build and moves the results so they
+# can be used as a comparison baseline against subsequent builds
+# that are run using build-and-compare.sh
+
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+
+rm -rf htmlPREVIOUS htmlPREVIOUS_SCRUBBED
+
+echo "Running clean build..."
+b2 clean
+b2
+
+echo "Moving results to htmlPREVIOUS..."
+mv html htmlPREVIOUS
+
+echo "Scrubbing htmlPREVIOUS and storing as htmlPREVIOUS_SCRUBBED for use by build-and-compare.sh..."
+cp -r htmlPREVIOUS htmlPREVIOUS_SCRUBBED
+cd htmlPREVIOUS_SCRUBBED
+grep -rl -f ${SCRIPT_DIR}/grep-expressions . | xargs sed -i -f ${SCRIPT_DIR}/sed-commands
diff --git a/src/boost/tools/docca/util/comparison/watch-all-builds.sh b/src/boost/tools/docca/util/comparison/watch-all-builds.sh
new file mode 100755
index 000000000..cf6f9fbcd
--- /dev/null
+++ b/src/boost/tools/docca/util/comparison/watch-all-builds.sh
@@ -0,0 +1,6 @@
+tail -f \
+~/boost/tools/docca/example/build_output.txt \
+~/boost/libs/static_string/doc/build_output.txt \
+~/boost/libs/url/doc/build_output.txt \
+~/boost/libs/json/doc/build_output.txt \
+~/boost/libs/beast/doc/build_output.txt