diff options
| -rw-r--r-- | doc/Makefile | 19 | ||||
| -rw-r--r-- | doc/breaking_rules.md | 89 | ||||
| -rw-r--r-- | doc/lkbib.ms | 2 |
3 files changed, 49 insertions, 61 deletions
diff --git a/doc/Makefile b/doc/Makefile index e98da46..4139f63 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -6,21 +6,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. @@ -36,7 +25,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 .] |