Merge branch 'what-and-how' into 'main'

How it works, how to use it

See merge request !4

README.md

@@ -2,12 +2,71 @@
 
 This is an example project to demonstrate Literate Programming to create [NetLogo](https://ccl.northwestern.edu/netlogo/) models from ODD+C protocols using [Yarner](https://github.com/mlange-42/yarner).
 
-## How to use this project
+The document you are currently reading contains the [ODD protocol](#rabies-model-odd-protocol) ([Grimm et al. 2006, 2010](#references)) of a model for Rabies in red foxes. The ODD description is interleaved with code blocks showing the NetLogo code used for the described aspect (ODD+C). Using the Literate Programming tool [Yarner](https://github.com/mlange-42/yarner), these code blocks are extracted from the document and arranged into a working NetLogo model.
 
-TODO
+* [How to use it](#how-to-use-it)
+* [How it works](#how-it-works)
+* [Rabies model - ODD protocol](#rabies-model-odd-protocol)
+* [References](#references)
+* [Appendix](#appendix)
+
+## How to use it
+
+**Read the ODD**
+
+The best way to understand how to use Literate Programming with Yarner to create a NetLogo model from an ODD protocol is to read the [ODD+C of the Rabies model](#rabies-model-odd-protocol), below. It contains the complete code of the model, except the UI elements.
+
+See section [How it works](#how-it-works) for how the model is extracted from this document.
+
+**Run from downloads**
+
+The [Downloads](https://git.ufz.de/oesa/literate-netlogo/-/jobs/artifacts/main/download?job=build) contain a folder `model` with files `Model.nlogo` and `Code.nls`. Open the `.nlogo` file with NetLogo.
+
+**Build from sources**
+
+1. [Install Yarner](https://mlange-42.github.io/yarner/installation.html)
+2. Clone the sources of this example:  
+   `git clone https://git.ufz.de/oesa/literate-netlogo.git`
+3. `cd` into folder `literate-netlogo`
+4. Run command `yarner` to extract the model code
+5. Open file `model/Model.nlogo` with NetLogo
+
+## How it works
+
+Yarner scans the document for code blocks and puts them together using macros. Each code block has a name, given in its first line and prefixed with `;-`:
+
+```netlogo
+;- A code block
+let x 0
+```
+
+When a code block is referenced by another code block using a macro with `; ==>`, it is placed inside the referencing code block:
+
+```netlogo
+;- Outer code block
+; ==> A code block.
+let y 1
+```
+
+The resulting extracted code would look like this:
+
+```netlogo
+let x 0
+let y 1
+```
+
+See the [Yarner documentation](https://mlange-42.github.io/yarner/) for a comprehensive guide and a description of all features.
 
 ## Rabies model - ODD protocol
 
+* [Purpose](#purpose)
+* [Entities, state variables, and scales](#entities-state-variables-and-scales)
+* [Process overview and scheduling](#process-overview-and-scheduling)
+* [Design concepts](#)
+* [Initialization](#)
+* [Input data](#)
+* [Submodels](#)
+
 ### Purpose
 
 The purpose of this model is to demonstrate how NetLogo models can be created from ODD protocols, using Literate Programming with Yarner.
@@ -220,6 +279,12 @@ to update-patches
 end
 ```
 
+## References
+
+Grimm V, Berger U, Bastiansen F, Eliassen S, Ginot V, Giske J, Goss-Custard J, Grand T, Heinz S, Huse G, Huth A, Jepsen JU, Jørgensen C, Mooij WM, Müller B, Pe’er G, Piou C, Railsback SF, Robbins AM, Robbins MM, Rossmanith E, Rüger N, Strand E, Souissi S, Stillman RA, Vabø R, Visser U, DeAngelis DL. 2006. **A standard protocol for describing individual-based and agent-based models**. *Ecological Modelling* 198:115-126.
+
+Grimm V, Berger U, DeAngelis DL, Polhill G, Giske J, Railsback SF. 2010. **The ODD protocol: a review and first update**. *Ecological Modelling* 221: 2760-2768.
+
 ## Appendix
 
 ### Code