Merge branch 'architecture-docs'

* architecture-docs:
  BUILD: only build developer docs if --with-docs is passed to configure
  docs/audiowmark.md: speed detection has been merged since the first docu version
  docs/audiowmark.md: update docs to say Hann window
  docs/audiowmark.md: describe general architecture
	Squashed history:
	* Add usage as reported by --help
	* Add `audiowmark get` overview
	* Add graph to describe components
	* Describe `audiowmark add` command usage
	* Add comment with build commands and notes
	* Fix basic HTML layout
	* Move "Modulation Frame Generator" into separate chart
	* Colorization adjustments
	* Explode conv_encode and randomize_bit_order
	* Fix block label
	* Add prepare_frame_mod, UpDownGen, mark_data
	* Describe mark_sync and frame_pos
	* Elaborate ab_generators
	* Describe gen_mix_entries and --linear
	* Describe mark_data
	* Describe init_frame_mod_vec
	* Properly layout ab_generators
	* Describe R1…R6 in detail
	* Elaborate on architecture, encoding and PRNG
	* Describe blocks and AES/CTR
	* Adjust layout and paper size
	* Add coarse extraction chart
	* Add frame_pos UpDownGen sync_finder fft_range BlockDecoder
	* Describe init_up_down
	* Add fft_analyzer, sync_fft_256, sync_decode, search_approx
	* Stretch graph
	* Document sync_select_by_threshold
	* Split SyncFinder and wmget graphs, refine wmget
	* Refine FFT and BlockDecoder details, sync_finder output
	* Fix all arrows and edges
	* Fix "Extracting Audio Watermarks" titles and subtitles
	* Describe refined search, document refining feedback
	* Sketch BlockDecoder functionality
	* Sketch ClipDecoder functionality
	* Adjust decoder fft_range
	* Document conv_decode_soft()
	* Complete the BlockDecoder documentation
	* Add bit vector description
	* Document ClipDecoder
	* Add decoder timing information
	* Adjust ClipDecoder color
	* Summarize synchronization detection
	* Describe zero padding in Mode::CLIP
	* Document result set printing
	* Maximum of 5 sync positions applies to ClipDecoder
	* Describe detection decision for A/B-Block
	* Add prose about watermark detection and extraction
	* Describe "Experimental Speed Detection"
	* Fix digraph titles and spelling in a few places
	* Adjust titles + boxes in "Modulation Frame Generator"
	* Adjust titles + boxes in "audiowmark add"
	* Adjust Power Measurement border
	* Adjust titles + boxes in "Synchronization Position Finder"
	* Add line break to improve digraph width
	* Small wording fixups
  docs/graphviz.py: pandoc filter to build dot graphs in SVG format
	Licensed BSD-3-Clause: https://spdx.org/licenses/BSD-3-Clause.html
	Based on https://github.com/jgm/pandocfilters/blob/master/examples/graphviz.py
  docs/.gitignore: list build files/dirs
  docs/Makefile.am: add build rules for audiowmark.pdf and audiowmark.html
  Makefile.am: build docs/
  configure.ac: generate docs/Makefile
Signed-off-by: Stefan Westerfeld <stefan@space.twc.de>

Makefile.am

 SUBDIRS = src tests
 ACLOCAL_AMFLAGS = -I m4
 
+if COND_WITH_DOCS
+  SUBDIRS += docs
+endif
+
 EXTRA_DIST = README.adoc Dockerfile

configure.ac

@@ -89,6 +89,11 @@ AC_DEFINE_UNQUOTED(HAVE_FFMPEG, $HAVE_FFMPEG, [whether ffmpeg libs are available
 AM_CONDITIONAL([COND_WITH_FFMPEG], [test "x$with_ffmpeg" != "xno"])
 dnl -------------------------------------------------------------------------
 
+dnl --------------- building documentation is optional ----------------------
+AC_ARG_WITH([docs], [AS_HELP_STRING([--with-docs], [build documentation])], [], [with_docs=no])
+AM_CONDITIONAL([COND_WITH_DOCS], [test "x$with_docs" != "xno"])
+dnl -------------------------------------------------------------------------
+
 dnl -------------------- address sanitizer ----------------------------------
 AC_ARG_ENABLE([asan], [AS_HELP_STRING([--enable-asan], [build using address sanitizer])],
 [
@@ -155,7 +160,7 @@ AC_LANG_POP([C++])
 # Less cluttered build output
 m4_ifdef([AM_SILENT_RULES], [AM_SILENT_RULES([yes])])
 
-AC_CONFIG_FILES([Makefile src/Makefile tests/Makefile tests/test-common.sh])
+AC_CONFIG_FILES([Makefile src/Makefile tests/Makefile tests/test-common.sh docs/Makefile])
 AC_OUTPUT
 
 # Output summary message
@@ -169,4 +174,5 @@ echo "  Use undefined behaviour sanitizer. .: $enable_ubsan (for debugging)"
 echo "  Use thread sanitizer . . . . . . . .: $enable_tsan (for debugging)"
 echo "  Use leak sanitizer . . . . . . . . .: $enable_lsan (for debugging)"
 echo "  Use stdc++ debug mode. . . . . . . .: $enable_debug_cxx (for debugging)"
-echo "  Use ffmpeg libs. . . . . . . . . . .: $with_ffmpeg (required for HLS)"
+echo "  Use ffmpeg libs. . . . . . . . . . .: $with_ffmpeg (use --with-ffmpeg to enable, required for HLS)"
+echo "  Build developer documentation  . . .: $with_docs (use --with-docs to enable)"

docs/.gitignore

+audiowmark.html
+audiowmark.pdf
+graphviz-images/

docs/Makefile.am

+# docs/Makefile.am
+
+doc_DATA  = audiowmark.pdf audiowmark.html
+
+GRAPHVIZ_PY = graphviz.py
+
+audiowmark.pdf: audiowmark.md $(GRAPHVIZ_PY)
+	pandoc -F $(GRAPHVIZ_PY) -V papersize:a4 -V geometry:margin=2cm $< -o $@
+
+audiowmark.html: audiowmark.md $(GRAPHVIZ_PY)
+	pandoc -F $(GRAPHVIZ_PY) $< -o $@
+
+# DEPS: apt install -y python3-pygraphviz python3-pandocfilters
+
+clean:
+	rm -f -r ../docs/graphviz-images/
+	rm -f $(doc_DATA)
+

docs/graphviz.py

+#!/usr/bin/env python3
+# Licensed BSD-3-Clause: https://spdx.org/licenses/BSD-3-Clause.html
+"""
+Pandoc filter to process code blocks with class "graphviz" into
+SVG based graphviz-generated images.
+
+Needs pygraphviz
+"""
+# Based on https://github.com/jgm/pandocfilters/blob/master/examples/graphviz.py
+
+import sys, os, pygraphviz
+from pandocfilters import toJSONFilter, Para, Image, RawBlock, get_filename4code, get_caption, get_extension, get_value
+
+# https://pandoc.org/lua-filters.html
+
+def graphviz (key, value, frmat, _):
+  if key == 'CodeBlock':
+    [[ident, classes, keyvals], code] = value
+    if "graphviz" in classes:
+      # sys.stderr.write ('Debug: ' + str (value) + '\n')
+      caption, typef, keyvals = get_caption (keyvals)
+      prog, keyvals = get_value (keyvals, u"prog", u"dot")
+      force, keyvals = get_value (keyvals, u"force", u"false")
+
+      filetype = get_extension (frmat, "svg", html ="svg", latex ="pdf")
+      dest = get_filename4code ("graphviz", str (value), filetype)
+
+      if force != u"false" or not os.path.isfile (dest):
+        g = pygraphviz.AGraph (string = code)
+        g.layout ()
+        g.draw (dest, prog = prog)
+        sys.stderr.write ('Create image: ' + dest + '\n')
+      if dest.endswith ('.svg'):
+        return RawBlock (u'html', '<object type="image/svg+xml" data="%s"></object>' % dest)
+      return Para ([Image ([ident, [], keyvals], caption, [dest, typef])])
+
+if __name__ == "__main__":
+  toJSONFilter (graphviz)