Update and proof read README.md(s)

SSoelvsten · Nov 30, 2023 · da5660b · da5660b
1 parent 224455a
commit da5660b
Show file tree

Hide file tree

Showing 2 changed files with 78 additions and 77 deletions.
diff --git a/README.md b/README.md
@@ -24,7 +24,7 @@ given machine.
        style="max-width:32rem; width:32rem;" />
 </div>
 <div align="center">
-  <p style="margin-bottom:1rem;">Figure: Running time solving *N*-Queens (lower is better).</p>
+  <p style="margin-bottom:1rem;">Figure: Running time solving *N* Queens (lower is better).</p>
 </div>
 
 
@@ -36,7 +36,8 @@ group at [Aarhus University](https://cs.au.dk).
 - [Documentation](#documentation)
 - [Dependencies](#dependencies)
 - [Usage](#usage)
-    - [Makefile targets](#makefile-targets)
+    - [Makefile Targets](#makefile-targets)
+    - [Playground](#playground)
     - [Examples](#examples)
 - [Contributions](#contributions)
 - [License](#license)
@@ -45,35 +46,37 @@ group at [Aarhus University](https://cs.au.dk).
 
 
 ## Documentation
-The documentation is available on [Github Pages](https://ssoelvsten.github.io/adiar/).
+The documentation is available on [Github
+Pages](https://ssoelvsten.github.io/adiar/). To compile it locally, you need
+*CMake* and *Doxygen* (see [Dependencies](#dependencies) and [Usage](#usage)).
 
 ## Dependencies
 The implementation is dependant on the the following external libraries
 
 - [**TPIE**](https://github.com/thomasmoelhave/tpie):
 
-  Framework for implementation of I/O efficient algorithms. It directly provides
-  sorting algorithms and a priotity queue. Both are much faster than the
-  algorithms in the _C++_ standard library
-  [[Vengroff94](#references), [Mølhave12](#references)].
+  Framework for implementation of I/O efficient algorithms. Among other things,
+  it provides an implementation of files, streams, sorting algorithms and
+  priotity queues. Both are much faster than the algorithms in the *C++*
+  standard library [[Vengroff94](#references), [Mølhave12](#references)].
 
 - [**Bandit**](https://github.com/banditcpp/bandit):
 
-  Unit testing framework that is easy-to-read and write.
+  Unit testing framework that is both easy to read and write.
 
 - [**CNL**](https://github.com/johnmcfarlane/cnl):
 
   Templated and efficient implementation of fixed-precision numbers.
 
-These are directly imported as submodules. If you have not cloned the repository
-recursively, then run the following command
+All of these are included within the repository as submodules. If you have not
+cloned the repository recursively, then run the following command
 
 ```bash
 git submodule update --init --recursive
 ```
 
 Other dependencies that we cannot provide as a submodule are shown below. The
-_ticked_ dependencies are mandatory to have installed.
+*ticked* dependencies are mandatory to have installed.
 
 - [x] **CMake** (3.21+) and a **C++ compiler** (C++17)
 
@@ -97,9 +100,9 @@ _ticked_ dependencies are mandatory to have installed.
   output as
   [DOT](https://en.wikipedia.org/wiki/DOT_(graph_description_language)) files.
   These can then be turned into a graphical representation by use of a number of
-  tools, such as _graphviz_ (2.40+).
+  tools, such as *graphviz* (2.40+).
 
-To install all of the above then run the respective below.
+To install all of the above, run the respective command below.
 
 | Operating System | Shell command                                                        |
 |------------------|----------------------------------------------------------------------|
@@ -109,62 +112,60 @@ To install all of the above then run the respective below.
 
 ## Usage
 
-### Makefile targets
+For how to use Adiar in your project, see the [Getting
+Started](https://ssoelvsten.github.io/adiar/page__getting_started.html) page in
+the documentation.
+
+### Makefile Targets
 
 The project is build with *CMake*, though for convenience I have simplified the
-*CMake* interactions to a single *Makefile* which works on a local machine. This
-script is continuously tested on *Ubuntu 22.04 LTS* and *Fedora 36+*.
+*CMake* interactions to a single *Makefile* which works on a local machine.
 
 The *Makefile* provides the following targets
 
-| target         | effect                                                               |
-|----------------|----------------------------------------------------------------------|
-| `build`        | Build the source files                                               |
-| `docs`         | Build the documentation files                                        |
-| `clean`        | Remove all build files                                               |
-|                |                                                                      |
-| `test`         | Run all unit tests (with _O2_ optimisations)                         |
-| `coverage`     | Run all unit tests (with no optimisations) and create _lcov_ report  |
-|                |                                                                      |
-| `main M=<MiB>` | Run the _main_ function in `src/main.cpp` with `<MiB>` MiB of memory |
+| target     | effect                                                |
+|------------|-------------------------------------------------------|
+| `build`    | Build the source files                                |
+| `docs`     | Build the documentation files                         |
+| `clean`    | Remove all build files                                |
+|            |                                                       |
+| `test`     | Build and run all unit tests                          |
+| `test/...` | Build and run a subset of the unit tests              |
+|            |                                                       |
+| `coverage` | Build and run all unit tests and create *lcov* report |
+
+### Playground
+
+To quickly get started running small pieces of code, we provide in
+*src/playground.cpp* a tiny program where all of the boiler-plate is taken care
+of. This can be useful for trying out a feature, creating a minimal example for
+a bug report, and to guide development of new features.
+
+To build and run the *main* function in `src/play.cpp` with `<MiB>` MiB of
+memory (default: 1024 MiB), just run the following make command.
+```bash
+make play M=<MiB>
+```
 
 ### Examples
-The *example/* folder contains examples for using the data structures in Adiar.
-The *README.md* file in said folder contains a more in-depth description of each
-of the examples. Even more examples and benchmarks are provided in a separate
-[BDD Benchmarking repository](https://github.com/SSoelvsten/bdd-benchmark).
-
-Each example takes a set of arguments as input, which can be parsed to the
-program as a makefile variable. That is, to change the value of *N* to to value
-follow the `make <target>` with `N=<value>`.
-
-**example/queens**
-
-| variable | description                   |
-|----------|-------------------------------|
-| _N_      | Board size (default: 8)       |
-| _M_      | Memory in MiB (default: 1024) |
-
-**example/knights-tour/[T]**
-
-The value **T** can either be *all* or *closed*.
 
-| variable | description                                      |
-|----------|--------------------------------------------------|
-| _N_      | Board size (default: 8)                          |
-| _M_      | Memory in MiB (default: 1024)                    |
+The *example/* folder contains larger examples for how to use Adiar. The
+*README.md* file in said folder contains a more in-depth description of each of
+the examples. For benchmarking Adiar against other BDD packages, see the [BDD
+Benchmarking repository](https://github.com/SSoelvsten/bdd-benchmark).
 
+You can use `make examples/<name>` to compile and run them.
 
 ## Contributions
 
-Adiar is not yet feature complete. If you feel anything is missing, please open
-an [issue](https://github.com/SSoelvsten/adiar/issues/new/choose).
+Adiar is not yet feature complete. If you notice anything is missing, please
+open an [issue](https://github.com/SSoelvsten/adiar/issues/new).
 
-Your contribution to the project is also very welcome! Our
-[issues](https://github.com/SSoelvsten/adiar/issues) list larger student
-projects but also many smaller things for *you* to help us with. Please read our
-[Contribution Guidelines](/CONTRIBUTING.md) before you start working on
-something.
+Your contribution to the project is also very welcome! We list multiple
+“[issues](https://github.com/SSoelvsten/adiar/issues)” where you can help -
+these tasks range from the smallest of tasks to entire student projects. Please
+get familiar with our [Contribution Guidelines](/CONTRIBUTING.md) before you
+start to work on something.
 
 
 ## License
@@ -189,20 +190,20 @@ or more of the papers in [docs/cite.md](https://ssoelvsten.github.io/adiar/page_
 ## References
 
 - [[Arge96](https://tidsskrift.dk/brics/article/view/20010/17643)]
-  Lars Arge. “_The I/O-complexity of Ordered Binary-Decision Diagram
-  Manipulation_”. In: _Efficient External-Memory Data Structures and
-  Applications_. (1996)
+  Lars Arge. “*The I/O-complexity of Ordered Binary-Decision Diagram
+  Manipulation*”. In: *Efficient External-Memory Data Structures and
+  Applications*. (1996)
 
 - [[Bryant86](https://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=1676819)]
-  Randal E. Bryant. “_Graph-Based Algorithms for Boolean Function Manipulation_”.
-  In: _IEEE Transactions on Computers_. (1986)
+  Randal E. Bryant. “*Graph-Based Algorithms for Boolean Function Manipulation*”.
+  In: *IEEE Transactions on Computers*. (1986)
 
 - [[Mølhave12](https://dl.acm.org/doi/pdf/10.1145/2367574.2367579)]
-  Thomas Mølhave. “_Using TPIE for Processing Massive Data Sets in C++_”. (2012)
+  Thomas Mølhave. “*Using TPIE for Processing Massive Data Sets in C++*”. (2012)
 
 - [[Vengroff94](https://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.38.3030)]
-  D.E. Vengroff. “_A transparent parallel I/O environment_”. In: _In Proc. 1994
-  DAGS Symposium on Parallel Computation_. pp. 117–134 (1994)
+  D.E. Vengroff. “*A transparent parallel I/O environment*”. In: *In Proc. 1994
+  DAGS Symposium on Parallel Computation*. pp. 117–134 (1994)
 
 ## Footnotes
 

diff --git a/example/README.md b/example/README.md
@@ -2,11 +2,11 @@
 ![examples](https://github.com/SSoelvsten/adiar/workflows/examples/badge.svg?branch=main)
 
 To benchmark the implementation and also to provide examples of how to use
-_Adiar_ in your project, we provide a few examples. Even more examples can be
+*Adiar* in your project, we provide a few examples. Even more examples can be
 found at the [BDD Benchmarking repository](https://github.com/SSoelvsten/bdd-benchmark).
 
-All examples have an _M_ variable to be set for the MiB of memory that is to be
-available to _Adiar_. The default is 1024 MiB.
+All examples have an *M* variable to be set for the MiB of memory that is to be
+available to *Adiar*. The default is 1024 MiB.
 
 <!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
 **Table of Contents**
@@ -23,38 +23,38 @@ available to _Adiar_. The default is 1024 MiB.
 
 **Target:** `make example/queens N=<?>`
 
-Solve the N-Queens problem for _N = `?`_ (default: `8`). This is done by
+Solve the N-Queens problem for *N = `?`* (default: `8`). This is done by
 constructing an BDD row-by-row that represents whether the row is in a legal
 state: is at least one queen placed on each row and is it also in no conflicts
 with any other? On this BDD we then counts the number of satisfying
 assignments [[kunkle10](#references)].
 
 To list the solutions, we take the same BDD, but instead of counting the number
 of assignments within, we use it to prune a recursive enumeration of all
-possible queen placements. For up to _N = 8_ we run both the solution counting
+possible queen placements. For up to *N = 8* we run both the solution counting
 procedure and the enumeration procedure.
 
 **Notice**: This is a pretty simple example and has all of the normal
-shortcomings for BDDs trying to solve the N-Queens problem. At around _N_ = 14
+shortcomings for BDDs trying to solve the N-Queens problem. At around *N* = 14
 the intermediate sizes explodes a lot. One can with about 100 GB of disk space
 or memory compute it.
 
 ## Knight's Tours
 
-**Files:** `knights_tour.cpp**
+**Files:** `knights_tour.cpp`
 
 **Target:** `make example/knights_tour/<?> N=<?>`
 
-Counts the number of Knight's Tours on an _N = `?`_ sized square board. Either
-_all_ or only the _closed_ tours are counted. This is done by combining ZDDs
+Counts the number of Knight's Tours on an *N = `?`* sized square board. Either
+*all* or only the *closed* tours are counted. This is done by combining ZDDs
 that describe the possible transitions at every time step together with ZDDs
-that make every square visited only once. If only the _closed_ tours are
+that make every square visited only once. If only the *closed* tours are
 supposed to be used, then the first time-step is fixed to the top-left corner
 and the next and last time-step fixed to the two possible moves by a Knight.
 
 ## References
 
 - [[Kunkle10](https://dl.acm.org/doi/abs/10.1145/1837210.1837222)] Daniel
-  Kunkle, Vlad Slavici, Gene Cooperman. “_Parallel Disk-Based Computation for
-  Large, Monolithic Binary Decision Diagrams_”. In: _PASCO '10: Proceedings of
-  the 4th International Workshop on Parallel and Symbolic Computation_. 2010
+  Kunkle, Vlad Slavici, Gene Cooperman. “*Parallel Disk-Based Computation for
+  Large, Monolithic Binary Decision Diagrams*”. In: *PASCO '10: Proceedings of
+  the 4th International Workshop on Parallel and Symbolic Computation*. 2010