Switch to more primitive way to maintain references, for compatibility with Gemini

3 files changed, 73 insertions, 52 deletions

diff --git a/doc/Makefile b/doc/Makefile
index deb3d8e..6a2159f 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -2,7 +2,7 @@
 .DELETE_ON_ERROR:
 
 .PHONY: all
-all: breaking_rules.pdf breaking_rules.html breaking_rules.txt bane.20.cdr15.html
+all: breaking_rules.pdf breaking_rules.html breaking_rules.txt bane.20.cdr15.html lkbib.txt
 
 # Stick with gfm for as long as possible.
 # Use stuff beyond that only where absolutely necessary.
@@ -18,6 +18,12 @@ breaking_rules.pdf: macros.ms breaking_rules.md refs.i
 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 > $@
 
+# None of setting GROFF_NO_SGR, using the "-c" option,
+# or piping through ul worked.
+# GROFF_NO_SGR=1 groff -Tutf8 -R -ms -k -Kutf8 -c macros.ms lkbib.ms | ul > $@
+lkbib.txt: macros.ms lkbib.ms refs.i
+	groff -Tlatin1 -R -ms -k -Kutf8 macros.ms lkbib.ms > $@
+
 refs.i: refs
 	indxbib $^
 
diff --git a/doc/breaking_rules.md b/doc/breaking_rules.md
index b8887b3..5c622f8 100644
--- a/doc/breaking_rules.md
+++ b/doc/breaking_rules.md
@@ -6,9 +6,6 @@ copyright: 2020 Darren Bane, CC BY-SA
 
 Recommendations for a process to refine prototypes into production-quality code
 are made.
-\.R1
-accumulate
-\.R2
 
 *TODO*: Q: re-cast much of this document as Architecture
 Decision Records? A: N
@@ -18,10 +15,7 @@ Decision Records? A: N
 The conventional wisdom is that prototypes should be discarded once the lessons
 have been learned,
 and the final product written again from scratch.
-In the spirit of
-\.[
-beck 1999
-\.]
+In the spirit of [1]
 I argue that improvements in development tools have
 invalidated this.
 
@@ -31,15 +25,8 @@ invalidated this.
 
 There is a long history of recommending prototyping as a way to construct
 systems.
-I would personally recommend
-\.[
-robertson agust\(i 1999
-\.]
-and
-\.[
-pitman 1994
-\.]
-.
+I would personally recommend [2]
+and [3].
 
 *NB*: I am almost certainly re-inventing a SmallTalk wheel.  However I
 argue that Lisp's combination of imperative & OO
@@ -59,15 +46,8 @@ arguing that it is possible to *refine* a prototype into a product.
 
 The first step is to construct a prototype,
 or in modern terminology a "Minimal Viable Product".
-These recommendations follow on from
-\.[
-robertson agust\(i 1999
-\.]
-and
-\.[
-bane 2008
-\.]
-.
+These recommendations follow on from [2]
+and [4].
 
 Reasons for choosing Common Lisp include:
 
@@ -82,11 +62,7 @@ Reasons for choosing Common Lisp include:
 * 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 as practical
-\.[
-bane 2020
-\.]
-.
+so cleave as close to ISLisp as practical[5].
 
 It was decided to use the imperative/object-oriented paradigm,
 partly for familiarity in industry and
@@ -112,15 +88,8 @@ Even though this is a prototype, attention should be paid to basic craftsmanship
 * Use `declare`
   to check the types of parameters in public interfaces.
 * Indent all the source code using Emacs.
-* Some minimal documentation, at least an overview README file
-\.[
-preston-werner 2010
-\.]
-and man (actually, mdoc) pages
-\.[
-dzonsons
-\.]
-.
+* Some minimal documentation, at least an overview README file[6]
+and man (actually, mdoc) 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.
@@ -205,19 +174,13 @@ The specification of input and output variables is best left at the level of tab
 
 ### Library
 
-This was the subject of
-\.[
-bane 2008
-\.]
-. The output artifacts are a module guide an set of module interface specs.
+This was the subject of [4].
+The output artifacts are a module guide an set of module interface specs.
 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
-\.[
-basic english
-\.].
+  tables with Basic English[8].
 * 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.
@@ -275,6 +238,14 @@ following the pattern above.
 
 A method for developing software from an incomplete understanding of the requirements is given.
 It is hoped that this is more effective than most of what is currently-used.
-\.[
-$LIST$
-\.]
+
+# References
+
+[1]Kent Beck, Extreme Programming Explained (1999).
+[2]David Robertson and Jaume Agust▒, Software Blueprints: Lightweight Uses of Logic in Conceptual Modelling, Addison Wesley Longman (1999).
+[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
new file mode 100644
index 0000000..7b052cf
--- /dev/null
+++ b/doc/lkbib.ms
@@ -0,0 +1,44 @@
+.R1
+accumulate
+.R2
+.TL
+References
+.AU
+Darren Bane
+.L= sec 1 refs
+References
+.IP 1.
+.[
+beck 1999
+.]
+.IP 2.
+.[
+robertson agust\('i 1999
+.]
+.IP 3.
+.[
+pitman 1994
+.]
+.IP 4.
+.[
+bane 2008
+.]
+.IP 5.
+.[
+bane 2020
+.]
+.IP 6.
+.[
+preston-werner 2010
+.]
+.IP 7.
+.[
+dzonsons
+.]
+.IP 8.
+.[
+basic english
+.]
+.[
+$LIST$
+.]