Added summary document

Jenkinsfile

@@ -0,0 +1,17 @@
+pipeline {
+    agent any
+
+    stages {
+        stage('Documentation') {
+            steps {
+                sh 'make docs'
+            }
+        }
+        stage('Deploy') {
+            steps {
+                archiveArtifacts artifacts: 'build/*.pdf', fingerprint: true
+                archiveArtifacts artifacts: 'build/*.html', fingerprint: true
+            }
+        }
+    }
+}

Makefile

@@ -12,26 +12,27 @@ VERSION=$(LAST_TAG:v%=%)$(PATCH)$(DIRTY)
 default: all
 
 # List of documents to produce from markdown
-DOCUMENTS=README
+DOCUMENTS=$(wildcard docs/%.mmd)
-
+HTML_DOCS=$(patsubst docs/%.mmd,build/%.html,$(DOCUMENTS))
-HTML_DOCS=$(patsubst %,%.html,$(DOCUMENTS))
+PDF_DOCS=$(patsubst docs/%.mmd,build/%.pdf,$(DOCUMENTS))
-PDF_DOCS=$(patsubst %,%.pdf,$(DOCUMENTS))
 
 all: docs
 
 docs: $(HTML_DOCS) $(PDF_DOCS)
 
-%.html: %.md
+build/%.html: docs/%.mmd
-	sed 's/%VERSION%/$(VERSION)/g' $^ | multimarkdown -t html > $@
+	sed 's/%VERSION%/$(VERSION)/g' $^ | multimarkdown -thtml > $@
 
-%.pdf: %.md
+build/%.pdf: docs/%.mmd
-	sed 's/%VERSION%/$(VERSION)/g' $^ | multimarkdown -t latex > $*.tex
+	sed 's/%VERSION%/$(VERSION)/g' $^ | multimarkdown -tlatex > build/$*.tex
-	pdflatex $*.tex
+	pdflatex -output-directory=build -interaction=batchmode build/$*.tex
-	pdflatex $*.tex
+	pdflatex -output-directory=build -interaction=batchmode build/$*.tex
-	-rm $*.aux $*.toc $*.log $*.tex $*.out
+	-rm $*.aux $*.toc $*.log build/$*.tex $*.out
 
 clean:
 	-rm $(HTML_DOCS) $(PDF_DOCS)
 
 print-%:
 	@echo '$*: $($*)'
+
+# Project-level note: mmd files can have comments via ```{=comment} ... or {=todo}

README.md

@@ -1,12 +1,8 @@
-vi: spell:spelllang=en:tw=72
+# Four-Letter Interleaved T(est/ask) Protocol
-Author: Louis A. Burke
-Affiliation: labprogramming.net
-Title: FLIT -- README
-CSS: ./flit.css
-Language: en
-LaTeX Leader: flit-leader.tex
-LaTeX Begin: flit-begin.tex
-LaTeX Footer: flit-footer.tex
-LaTeX Header Level: 3
 
-# Four-Letter Interleaved T(ask/est) Protocol
+FLIT is a protocol for test reporting.
+
+
+## License
+
+This project is [Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0) licensed.

docs/flit-begin.tex

@@ -0,0 +1 @@
+\begin{document}

docs/flit-footer.tex

@@ -0,0 +1 @@
+\end{document}

docs/flit-leader.tex

@@ -0,0 +1,12 @@
+\documentclass{article}
+
+\usepackage{hyperref}
+\usepackage{tabularx}
+\usepackage{tabulary}
+\usepackage{booktabs}
+\usepackage[normalem]{ulem}
+\usepackage{glossaries}
+\usepackage{soul}
+
+\setcounter{secnumdepth}{0}
+%\renewcommand{\chapternumberline}[1]{}% Gobble chapter numbers in TOC

docs/flit.css

@@ -0,0 +1,5 @@
+code {
+    font-size: 12pt;
+    font-weight: bold;
+    color: darkblue;
+}

docs/summary.mmd

@@ -0,0 +1,65 @@
+---
+vi: spell:spelllang=en:tw=72:ft=markdown
+Author: Louis A. Burke
+Affiliation: labprogramming.net
+Title: FLIT -- Summary
+CSS: docs/flit.css
+Language: en
+LaTeX Leader: docs/flit-leader.tex
+LaTeX Begin: docs/flit-begin.tex
+LaTeX Footer: docs/flit-footer.tex
+LaTeX Header Level: 3
+---
+
+# Four-Letter Interleaved T(ask/est) Protocol
+
+Version: **%VERSION%**
+
+{{TOC}}
+
+---
+
+## Comparison with popular test formats
+
+| Feature                  | FLIT       | [TAP14]    | [Robot]    | [xUnit]    |
+| :----------------------- | :--------: | :--------: | :--------: | :--------: |
+| [Concurrent]             | {++YES++}  | {--NO--}   | {++YES++}  | {++YES++}  |
+| [Language Agnostic]      | {++YES++}  | {++YES++}  | {++NO++}   | {++YES++}  |
+| [Human-Readable]         | {++YES++}  | {++YES++}  | {==SOME==} | {--NO--}   |
+| [Hierarchical]           | {++YES++}  | {--NO--}   | {++YES++}  | {==SOME==} |
+
+### Concurrent
+
+FLIT supports concurrent test execution by allowing outputs for multiple
+tests to be interleaved without loss of information. TAP14, by contrast,
+requires that all test outputs occur in order. Robot and xUnit both
+support concurrent tests, though they don't necessarily display partial
+results accurately in such cases.
+
+### Language Agnostic
+
+FLIT is a text-based, line oriented protocol that can be implemented
+easily in most programming languages, similarly to TAP14. xUnit is also
+a mostly language agnostic system, though its protocol is not as simple.
+Robot framework generates its own report format from robot files. Custom
+reporters can be implemented in Python or Java, but not arbitrary
+languages.
+
+### Human Readable
+
+FLIT output is human readable, though perhaps not as readable as some
+other formats. On the other hand, Robot and xUnit outputs require
+further processing or tools (such as web browsers) to view properly.
+
+### Hierarchical
+
+FLIT tests can be nested as deeply as desired. This is common to most
+test frameworks to some degree. However, they often do not properly
+treat nested tests within steps correctly. In particular, TAP14 does not
+support the type of nested sub-steps that make Robot tests so easy to
+debug.
+
+[>FLIT]: Four-Letter Interleaved T(est/ask)
+[TAP14]: https://testanything.org/tap-version-14-specification.html
+[Robot]: https://robotframework.org/
+[xUnit]: https://junit.org/junit5/