Making changes

2 files changed, 33 insertions, 7 deletions

diff --git a/doc/Makefile b/doc/Makefile
index 8e0f283..9cd37e5 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -11,9 +11,9 @@ all: breaking_rules.pdf breaking_rules.html
 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 > $@
 
-# Headers aren't emitted currently
+# On macOS only, headers aren't emitted currently
 breaking_rules.html: macros.ms breaking_rules.md refs.i
-	( cat macros.ms; lowdown -sTms breaking_rules.md ) | groff -Thtml -i -t -R -ms -k -Kutf8 > $@
+	( cat macros.ms; lowdown -sTms breaking_rules.md ) | groff -Txhtml -i -t -R -ms -k -Kutf8 > $@
 
 refs.i: refs
 	indxbib $^
diff --git a/doc/breaking_rules.md b/doc/breaking_rules.md
index aa3cb89..d5b399c 100644
--- a/doc/breaking_rules.md
+++ b/doc/breaking_rules.md
@@ -22,6 +22,8 @@ beck 1999
 I argue that improvements in development tools have
 invalidated this.
 
+*TODO*: case study
+
 *Colophon*: this document tries to depend only on GFM,
 in the same spirit as the software.
 The use of tools like
@@ -81,9 +83,8 @@ but there is no need to force it at the start.
 
 A JSON-RPC library was not difficult to write.
 
-## Imperative/Object-oriented paradigm
-
-Here, the following technology is recommended:
+It was decided to use the imperative/object-oriented paradigm.
+The following technology is recommended:
 
 * The OpenLisp interpreter.
 * Emacs for the view layer
@@ -98,7 +99,7 @@ Even though this is a prototype, attention should be paid to basic craftsmanship
   to check the types of parameters in public interfaces
 * Some minimal documentation, at least an overview README file and man pages.
 
-### Further work
+## Further Work
 
 This is probably the most work that makes sense
 without earning money.
@@ -109,7 +110,9 @@ without earning money.
 
 # Refinement to Production-Quality
 
-I argue that there is a repeatable procedure to improve the quality of a
+First, software at the level of the previous section is quite usable.
+It should be confirmed that further improvement is, in fact, required.
+If so, I argue that there is a repeatable procedure to improve the quality of a
 (reasonably well-written) prototype to a releaseable product.
 
 First, ensure that the surrounding infrastructure is in place:
@@ -127,6 +130,29 @@ Then, the following code & documentation improvements should be made:
 * Port some of the trivial-\* CL libraries from quicklisp where justified.
 * Port to core-lisp on platform.sh?
 
+## Documentation Details
+
+I think it is a good idea to keep the separation between library and UI code.
+And JSON-RPC is perfectly adequate for that.
+
+### Library
+
+This was the subject of
+\.[
+bane 2008
+\.]
+. However, much of the work of dedicated documentation is better done in 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 is better done with contracts.
+  Tables with Simple English are still a good idea for initial work.
+  
+### UI
+
+This involves filling in any blanks that still need to be filled after the man pages have been written.
+There is also the system-level documentation to consider, some of which is fine in a README.
+The specification of input and output variables is best left at the level of tables and Simple English again.
+
 # Conclusion
 
 A method for developing software from an incomplete understanding of the requirements is given.