Refactor docs again

3 files changed, 49 insertions, 61 deletions

diff --git a/doc/Makefile b/doc/Makefile
index d481321..29dd3db 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -4,21 +4,10 @@
 GEMINI := breaking_rules.gmi bane.20.cdr15.gmi
 
 .PHONY: all
-all: breaking_rules.pdf breaking_rules.html breaking_rules.txt bane.20.cdr15.html lkbib.txt
+all: $(GEMINI) lkbib.txt
 
-# Stick with gfm for as long as possible.
-# Use stuff beyond that only where absolutely necessary.
-# Similar to code, YAGNI.
-
-breaking_rules.pdf: macros.ms breaking_rules.md refs.i
-	( cat macros.ms; lowdown -sTms breaking_rules.md ) | pdfroff -i -t -R -mspdf -k -Kutf8 > $@
-
-# On macOS only, headers aren't emitted currently
-%.html: macros.ms %.md refs.i
-	( cat macros.ms; lowdown -sTms $(filter %.md,$^) ) | groff -Txhtml -i -t -R -ms -k -Kutf8 > $@
-
-breaking_rules.txt: macros.ms breaking_rules.md refs.i
-	( cat macros.ms; lowdown -sTms breaking_rules.md ) | env GROFF_NO_SGR=t groff -Tlatin1 -i -t -R -ms -k -Kutf8 -c | ul > $@
+# Write gfm.
+# Beyond that, YAGNI.
 
 # None of setting GROFF_NO_SGR, using the "-c" option,
 # or piping through ul worked.
@@ -34,7 +23,7 @@ refs.i: refs
 
 .PHONY: clean
 clean:
-	$(RM) breaking_rules.pdf breaking_rules.html breaking_rules.txt bane.20.cdr15.html
+	$(RM) $(GEMINI) lkbib.txt
 
 .PHONY: push
 push: $(GEMINI)
diff --git a/doc/breaking_rules.md b/doc/breaking_rules.md
index 94c7141..29f20d1 100644
--- a/doc/breaking_rules.md
+++ b/doc/breaking_rules.md
@@ -21,7 +21,7 @@ invalidated this.
 
 *TODO*: case study
 
-# Literature Review
+# Previous Work
 
 There is a long history of recommending prototyping as a way to construct
 systems.
@@ -49,36 +49,38 @@ or in modern terminology a "Minimal Viable Product".
 These recommendations follow on from [2]
 and [4].
 
-Reasons for choosing Common Lisp include:
+The following is probably the most work that makes sense
+without earning money.
+
+## Design Decisions
+
+The programming language chosen is a particular style of Common Lisp.
+A clean subset of CL is desired,
+so cleave as [close to ISLisp](bane.20.cdr15.md) as practical[5].
+Reasons for this decision include:
 
-* Procedural and object-oriented programming is commonly taught.
+* Contrary to a lot of other languages, Lisp is fairly paradigm-agnostic.
+  Imperative, object-oriented and (limited) functional programming is fairly natural.
+* The imperative and object-oriented paradigms are commonly taught,
+  used in industry,
+  and have a small "impedence mismatch" to current hardware.
 * The existence of quicklisp.
   Popularity is not really a reason for choosing Common Lisp over ISLisp,
   but slotting into quicklisp *is*.
-* Although the official ANSI standard is moribund,
-  quasi-standard libaries are recommended on the
-  [awesome list](https://github.com/CodyReichert/awesome-cl),
-  or [portability layers](http://portability.cl/).
-* Contrary to a lot of other languages, it is fairly paradigm-agnostic.
 
-At the same time, I want a clean subset of CL,
-so cleave as [close to ISLisp](bane.20.cdr15.md) as practical[5].
-
-It was decided to use the imperative/object-oriented paradigm,
-partly for familiarity in industry and
-partly for a reduced "impedence mismatch" to current hardware.
-The following technology is recommended:
+Detailed implementations, libraries, etc. are as follows:
 
 * The SBCL compiler.
-* ltk for the view layer.
+* Avoid multi-threading at this stage,
+  event-driven should do the job.
+* For simple multi-user,
+  use IRCv3, including the bots (nickserv, chanserv), and tilde.chat.
 
-For simple multi-user,
-use the IRCv3 bots (nickserv, chanserv) and IRCCloud or similar.
-But avoid multi-threading at this stage,
-event-driven should do the job.
+### Dependencies
 
-The following is probably the most work that makes sense
-without earning money.
+For the prototyping phase,
+you should *really* limit yourself to the ISLisp subset.
+If absolutely necessary you can choose some of the libraries mentioned in the "Productisation" section below.
 
 ## Coding standards
 
@@ -88,14 +90,14 @@ Even though this is a prototype, attention should be paid to basic craftsmanship
   supported by OpenLisp
 * Write one-sentence docstrings for at least each public fun and class
 * Use `declare`
-  to check the types of parameters in public interfaces.
+  to check the types of parameters in public interfaces (see below).
 * Indent all the source code using Emacs.
-* Some minimal documentation, at least an overview [README](https://tom.preston-werner.com/2010/08/23/readme-driven-development.html) file[6]
+* Some minimal documentation, at least an overview [README](https://tom.preston-werner.com/2010/08/23/readme-driven-development.html) file
   and man (actually, [mdoc](https://manpages.bsd.lv/toc.html)) pages[7].
 * Certain parts of a system justify greater detail for a *complete* specification.
   These are (newly-designed) network protocols and complex persistent data models.
-  If there is no standard protocol, I recommend using JSON-RPC as a base and following the documentation style of LSP.
-  The data models should be documented as commented SQL DDL.
+  For new protocols, use JSON-RPC as a base and follow the documentation style of LSP.
+  Data models should be documented as commented SQL DDL.
 
 ### Run-time type-checking
 
@@ -109,17 +111,6 @@ For example, the following:
   (the fixnum (+ x 1)))
 ```
 
-## Rejected alternatives
-
-You could use an integrated environment.
-With Emacs and JSON-RPC
-(ELisp and ISLisp are not identical but are very similar),
-but I reject this because jsonrpc is not "blessed" and
-I don't want to maintain my own.
-
-Full DbC would be another nice-to-have,
-but I settle for a pattern using `(declare`.
-
 # Refinement to Production-Quality
 
 First, software at the level of the previous section is quite usable.
@@ -142,7 +133,7 @@ Then, the following code & documentation improvements should be made:
 * Document the system more exhaustively
 * Can use more of quicklisp, e.g. the trivial-\* libraries
 * Can multi-thread to take advantage of all cores
-* Port to platform.sh?
+* Port to platform.sh? Modern WWW stacks are extremely complex, it would be great to do without.
 
 Since we have a working prototype,
 it may make sense to write the documentation (and contracts, and tests) "bottom-up":
@@ -183,7 +174,7 @@ However, some of this documentation is better in the source code:
 
 * The summary of functions should be taken care of by having the public functions and classes commented.
 * The formal requirement for function behaviour can be done with
-  tables with [Basic English](https://en.wikipedia.org/wiki/Basic_English)[8].
+  tables with [Basic English](https://en.wikipedia.org/wiki/Basic_English).
 * Although full design-by-contract may be out of reach
   a poor-man's version can be used with public functions following a pattern.
   This can also do some of the formal requirements.
@@ -208,22 +199,30 @@ Note that I prefer HTMX & ReST (following Fielding) to single-page applications
 
 ## Dependencies
 
-For the prototyping phase,
-you should *really* limit yourself to the ISLisp subset.
-For productisation you may want to make more of an effort,
-but I would still recommend limiting to the following,
+For productisation you may want to add more features.
+
+Although the official ANSI standard is moribund,
+quasi-standard libaries are recommended on the
+[awesome list](https://github.com/CodyReichert/awesome-cl),
+or [portability layers](http://portability.cl/).
+Usage should be limited as follows,
 in order of preference.
 The language/library split isn't as clear in CL as in some other languages,
 but use your judgement.
 
 * For "language" functionality, "[Portability layers](http://portability.cl/)" from that list
 * For "library" functionality, any "stars" from the [Awesome-CL](https://github.com/CodyReichert/awesome-cl) list
-* Any of the `trivial-` libraries from that list. These may be *forked* and maintained locally.
+* Any of the `trivial-` libraries from that list.
 * Any other `trivial-` libraries available in Quicklisp.
 * Other libraries available in Quicklisp.
 
 The `trivial-` libraries may be *forked* and maintained locally.
 
+For example:
+* ltk for the view layer.
+* For IRC,
+  use trivial-irc.
+
 ## Testing
 
 Unit (FiveAM) tests grow in parallel with the module interface specs.
@@ -249,6 +248,4 @@ It is hoped that this is more effective than most of what is currently-used.
 [3]Kent Pitman, Accelerating Hindsight: Lisp as a Vehicle for Rapid Prototyping (1994).  
 [4]Darren Bane, Design and Documentation of the Kernel of a Set of Tools for Working With Tabular Mathematical Expressions, University of Limerick, Ireland (19 Jul 2008).  
 [5]Darren Bane, An ISLisp-like subset of ANSI Common Lisp, Ireland (21 Aug 2020).  
-[6]Tom Preston-Werner, Readme Driven Development, San Francisco, CA, USA (23 Aug 2010). available: https://tom.preston-werner.com/2010/08/23/readme-driven-development.html [accessed 27 May 2020].  
 [7]Kristaps Dzonsons, Practical UNIX Manuals. available: https://manpages.bsd.lv/toc.html [accessed 9 Oct 2020].  
-[8]"Basic English" in Wikipedia. available: https://en.wikipedia.org/wiki/Basic_English [accessed 28 May 2020].  
diff --git a/doc/lkbib.ms b/doc/lkbib.ms
index 7b052cf..d9e095c 100644
--- a/doc/lkbib.ms
+++ b/doc/lkbib.ms
@@ -28,6 +28,7 @@ bane 2008
 bane 2020
 .]
 .IP 6.
+Unused:
 .[
 preston-werner 2010
 .]
@@ -36,6 +37,7 @@ preston-werner 2010
 dzonsons
 .]
 .IP 8.
+Unused:
 .[
 basic english
 .]