diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile | 8 | ||||
| -rw-r--r-- | doc/breaking_rules.md | 73 | ||||
| -rw-r--r-- | doc/lkbib.ms | 44 |
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$ +.] |