update docs

doc/spec/getstarted.kk.md

@@ -41,6 +41,8 @@ libraries, package management, and deep IDE integration.
 [build]: https://github.com/koka-lang/koka/#build-from-source
 [vsprompt]: https://docs.microsoft.com/en-us/cpp/build/how-to-enable-a-64-bit-visual-cpp-toolset-on-the-command-line?view=vs-2019
 [reusetech]: https://www.microsoft.com/en-us/research/publication/reference-counting-with-frame-limited-reuse-extended-version/
+[fip-paper]: https://www.microsoft.com/en-us/research/publication/fp2-fully-in-place-functional-programming/
+[trmc-paper]: https://www.microsoft.com/en-us/research/publication/tail-recursion-modulo-context-an-equational-approach/
 
 ## Installing the compiler { #install }
 

doc/spec/install.mdk

@@ -17,12 +17,14 @@
 
 [Homebrew]: https://brew.sh
 
+<!--
 On macOS (x64, M1), you can install and upgrade &koka; using Homebrew:
 
 &acopy;
 {.copy; data-value:"brew install koka"}
 
     \(**brew install koka**\)
+-->
 
 On Windows (x64), open a ``cmd`` prompt and use:
 
@@ -31,20 +33,32 @@ On Windows (x64), open a ``cmd`` prompt and use:
 
     \(**curl -sSL -o %tmp%\install-koka.bat https://github.com/koka-lang/koka/releases/latest/download/install.bat && %tmp%\install-koka.bat**\)
 
-On Linux (x64, arm64) and FreeBSD (x64) (and macOS), you can install &koka; using:
+On Linux (x64) and macOS (x64, arm64 (M1/M2)), you can install &koka; using:
 
 &acopy;
 {.copy; data-value:"curl -sSL https://github.com/koka-lang/koka/releases/latest/download/install.sh | sh"}
 
     \(**curl -sSL https://github.com/koka-lang/koka/releases/latest/download/install.sh &bar; sh**\)
 
+(If you previously installed Koka on macOS using `brew`, do an `brew uninstall koka` first).
+On other platforms it is usually easy to build Koka from [source](https://github.com/koka-lang/koka#build-from-source) instead.
+
+<!--
+On macOS (x64, M1), you can install and upgrade &koka; using Homebrew:
+
+&acopy;
+{.copy; data-value:"brew install koka"}
+
+    \(**brew install koka**\)
+
 There are also installation packages for various Linux distributions:
 Ubuntu/Debian ([x64][ubuntu-x64], [arm64][ubuntu-arm64]),
 Alpine ([x64][alpine-x64], [arm64][alpine-arm64]),
 Arch ([x64][arch-x64], [arm64][arch-arm64]),
 Red Hat ([x64][rhel-x64]), and
 openSUSE ([x64][opensuse-x64]).
 {text-align:left}
+-->
 
 After installation, verify if &koka; installed correctly:
 

doc/spec/koka.bib

@@ -1,3 +1,50 @@
+@inproceedings{Lorenzen:fip,
+  author  = {Lorenzen, Anton and Leijen, Daan and Swierstra, Wouter},
+  title   = {FP$^2$: Fully in-Place Functional Programming},
+  year    = 2023,
+  booktitle = {Proceedings of the 28th ACM SIGPLAN International Conference on Functional Programming (ICFP'2023)},
+  series = {ICFP'23},
+  location = {Seattle, WA, USA},  
+  month  = Sep,
+  note = {See also \cite{Lorenzen:fip-tr}}
+}
+
+@techreport{Lorenzen:fip-tr,
+  author  = {Lorenzen, Anton and Leijen, Daan and Swierstra, Wouter},
+  title   = {FP$^2$: Fully in-Place Functional Programming},
+  year    = 2023,
+  month   = may,
+  institution = {Microsoft Research},
+  number  = {MSR-TR-2023-19},
+  url     = {https://www.microsoft.com/en-us/research/publication/fp2-fully-in-place-functional-programming}
+}
+
+
+@article{Leijen:trmc,
+  author = {Leijen, Daan and Lorenzen, Anton},
+  title = {Tail Recursion Modulo Context: An Equational Approach},
+  year = {2023},
+  issue_date = {January 2023},
+  volume = {7},
+  number = {POPL},
+  doi = {10.1145/3571233},
+  journal = {Proc. ACM Program. Lang.},
+  month = jan,
+  articleno = 40,
+  numpages = 30,  
+  note = {See also \cite{Leijen:trmc-tr}}
+}
+
+@TechReport{Leijen:trmc-tr,
+  author = {Leijen, Daan and Lorenzen, Anton},
+  title = {Tail Recursion Modulo Context -- An Equational Approach},
+  year = 2022,
+  month = Jul,
+  institution = {Microsoft Research},
+  number = {MSR-TR-2022-18}
+}
+
+
 @article{Boucher:trojan,
     title = {Trojan {Source}: {Invisible} {Vulnerabilities}},
     author = {Nicholas Boucher and Ross Anderson},

doc/spec/news.mdk

@@ -1,6 +1,11 @@
 ~ begin news
 News:
 
+* 2023-07-03: Koka v2.4.2 released: add support for `fip` and `fbip` keywords described
+  in &ldquo;FP<sup>2</sup>: Fully in-Place Functional Programming&rdquo; 
+  (ICFP'23) [[pdf](https://www.microsoft.com/en-us/research/uploads/prod/2023/05/fbip.pdf)].
+  Various fixes and performance improvements.
+
 * 2021-02-04 (pinned) The [Context Free](https://www.youtube.com/channel/UCS4FAVeYW_IaZqAbqhlvxlA) 
   youtube channel posted a short and fun [video](https://www.youtube.com/watch?v=olISecOUX1g&t=959s)
   about effects in Koka (and 12 (!) other languages).

doc/spec/why.kk.md

@@ -306,7 +306,7 @@ void map( list_t xs, function_t f,
 }
 ````
 
-Moreover, the &koka; compiler also implements _tail-recursion modulo cons_ (TRMC)
+Moreover, the &koka; compiler also implements _tail-recursion modulo cons_ (TRMC) [@Leijen:trmc;@Leijen:trmc-tr]
 and instead of using a recursive call, the function is eventually optimized 
 into an in-place updating loop for the fast path, similar to 
 the C code example on the right. 
@@ -323,6 +323,11 @@ functional style.
 [Learn more about FBIP &adown;](book.html#sec-fbip)
 {.learn}
 
+[Read the paper on fully in-place functional programming][fip-paper]
+{.learn}
+
+[Read the paper on generalized tail-recursion modulo cons][trmc-paper]
+{.learn}
 
 
 ## Specialization
@@ -426,7 +431,7 @@ Here we see too that the node `t` is freed explicitly as soon as it is
 no longer live. This is usually earlier than scope-based deallocation 
 (like RAII) and therefore Perceus can guarantee to be _garbage-free_ 
 where in a (cycle-free) program objects are always immediatedly
-deallocated as soon as they become unreachable [@Reinking:perceus;@Lorenzen:reuse-tr].
+deallocated as soon as they become unreachable [@Reinking:perceus;@Lorenzen:reuse-tr;@Lorenzen:fip;@Lorenzen:fip-tr].
 Moreover, it is fully deterministic and behaves just like regular 
 malloc/free calls.
 Reference counting may still seem expensive compared to trace-based garbage collection
@@ -443,3 +448,5 @@ in practice.
 [Read the technical report on garbage-free and frame-limited reuse][reusetech]
 {.learn}
 
+[Read the technical report on fully in-place functional programming][fip-paper]
+{.learn}

readme.md

@@ -15,6 +15,7 @@
 # Koka: a Functional Language with Effects
 
 _Koka v2 is a research language that currently under heavy development with the new C backend_
+
 _Latest release_: v2.4.2, 2023-07-03 ([Install]).
 
 <a href="https://koka-lang.github.io/koka/doc/book.html#why-handlers"><img align="right" width="300" src="doc/snippet-yield.png" /></a>
@@ -508,6 +509,6 @@ Also as MSR-TR-2021-5, Mar, 2021.
 10. Anton Lorenzen and Daan Leijen. &ldquo; Reference Counting with Frame-Limited Reuse&rdquo; Microsoft Research
 technical report MSR-TR-2021-30, Nov 2021, (updated Mar 2022, v2). [pdf](https://www.microsoft.com/en-us/research/publication/reference-counting-with-frame-limited-reuse-extended-version/)
 
-11. Anton Lorenzen, Daan Leijen, and Wouter Swierstra. &ldquo; FP<sup>2</sup>: Fully in-Place Functional Programming&rdquo;
+11. Anton Lorenzen, Daan Leijen, and Wouter Swierstra. &ldquo;FP<sup>2</sup>: Fully in-Place Functional Programming&rdquo;
 The 28th ACM SIGPLAN International Conference on Functional Programming (ICFP), September 2023. 
 [pdf](https://www.microsoft.com/en-us/research/uploads/prod/2023/05/fbip.pdf) (extended tech. report MSR-TR-2023-19, May 2023).

util/docs.kk

@@ -16,7 +16,7 @@ import std/os/process
 
 val header = "usage:\n stack exec koka -- util/docs [-- [options]]\n\noptions:"
 
-struct iflags 
+ref struct iflags 
   publish  : bool  = False
   version  : string = ""
   speconly : bool  = False