init cgi script and html form

README.md

@@ -14,36 +14,30 @@ bibliography: REFERENCES.bib
 
 ### Gale-Shapley Deferred Acceptance
 
-The most basic versions of the stable matching problem was outlined and solved by [@gale&shapley1962]. 
+The most basic version(s) of the stable matching problem was outlined and solved in [@gale&shapley1962] and won Shapley the 
+[2012 Nobel Prize in Economics](https://www.nobelprize.org/prizes/economic-sciences/2012/popular-information/).
+
+The basic problem being solved is as follows:
+
+#### Stable Marriage Problem
+The "Stable Marriage problem" TODO
 
 TODO
 
-## Usage
-Using `carousel` is pretty simple once it's set up: given some input rankings, and some post-selection criteria 
-the program should generate a landscape of valid matching solutions for you to choose from (and can generate more on request).
-
-### Installation, Setup, Dependencies & Tooling
-There are a number of ways to guarantee you have the required dependencies to run `carousel`.
-The most complete method is using `uv` (with `nix` and `direnv`), but a plain/more barebones setup using `venv` is also possible.
-
-#### Setup and run with `uv`
-`carousel` was developed using the the [`uv`](https://github.com/astral-sh/uv) package and project manager.
+#### College Admissions Problem 
+Solving the stable marriage problem also provides a solution to the "College Admissions Problem", 
+with just a little more work.
 
 TODO
 
-#### Raw setup with `venv`
-It's possible to only use only default Python tooling, if so desired, via the 
-[`venv` module](https://docs.python.org/3/library/venv.html).
+## Data - Input/Output
+All [input table formats supported by `polars`](https://docs.pola.rs/user-guide/io/) are supported by `carousel` (`csv`, `excel`, `json` to name a few), 
+which accepts a few inter-related tabular schemes for the input/output data.
 
-TODO
-
-#### Convenience [`direnv`](https://github.com/direnv/direnv) and [`nix`](https://github.com/NixOS/nix) environment management and [`just`](https://github.com/casey/just) taskrunner.
-TODO
-
-### Matching: Input & Output
-
-All [input table formats supported by `polars`](https://docs.pola.rs/user-guide/io/) are supported by `carousel`.
-Input data should be in one of three forms:
+### Input
+Input describes the preferences/rankings of the "applicants" of "reviewers" to which they will be matched (possibly many-to-one, as in the "College Admission Problem"),
+as well as the preferences/rankings for the reviwers of applicants.
+Input should be in one of three forms:
 
 #### Preferences
 Preferences enumerate by-name some preferences in descending order, 
@@ -78,6 +72,8 @@ a pair of corresponding rankings, *or* a matrix encoding both rankings at once:
 | CaseMed |   (3, 2)   |  (1, 1) |   (2, 3)  |
 | Emory   |   (2, 1)   |  (3, 3) |   (1, 2)  |
 
+### Output
+
 #### Matching
 A matching is a table whose rows list the applicants matched to each reviewer
 e.g. a matching from the med-school ranking matrix in the previous section might look like
@@ -99,10 +95,52 @@ TODO check/make stable.
 
 TODO matching more people per school e.g.
 
-### Matching: Post-Selection
+
+
+
+## Usage
+
+There are 4 main ways to use Carousel:
+
+### UO Pages Server - CGI Form
+An HTML form submission interface is hosted at
+
+> [`https://pages.uoregon.edu/tgorordo/forms/carousel.html`](https://pages.uoregon.edu/tgorordo/forms/carousel.html)
+
+using the [pages.uoregon.edu CGI feature](https://service.uoregon.edu/TDClient/2030/Portal/KB/ArticleDet?ID=43069).
+
+Submit your applicant and reviewer preferences in tabular form,
+or as excel uploads and the server will return a table of matches for you to choose from.
+
+### Command Line Binary
+
+TODO
+
+### GUI Binary
+
+TODO
+
+### Python Library/Development
+If you prefer to invoke `carousel` directly (or incorporate it as a library into another script)
+in a python environment instead of using any of the bundled/released versions of the program described above (or wish to
+reproduce those bundles), you can do so using the [`uv` environment/package/project manager](https://github.com/astral-sh/uv)
+or a raw python virtual environment using the [`venv` module](https://docs.python.org/3/library/venv.html)
+(if you need an intro to python `venv`s see [this page](https://pages.uoregon.edu/tgorordo/uoph410-510a_Image-Analysis/venvs.html)).
+
+Some extra command-line development conveniences are available if you use the tools:  
+
+- [`just`](https://github.com/casey/just) is a taskrunner that can execute the provided `justfile` of some common useful commands.
+- [`direnv`](https://github.com/direnv/direnv) with [`nix` (shell)](https://github.com/NixOS/nix) can guarantee minimal development tooling without polluting your broader environment. i.e. they can auto-install and run all of carousel's tooling in an environment specific to your development directory.
+
+but everything provided by these tools can also be done using more standard/default shell tooling. 
+[`uv`](https://github.com/astral-sh/uv) as your package/environment manager is highly recommended, however.
+
+TODO
+
+## Post-Selection
 It's often desirable to enforce additional criteria on solutions 
 that are not well-posed within the core optimization problem.
-Since the solver itself is stochastic, these are often most easily implemented 
+Since the solver itself is stochastic to some extent, these are often most easily implemented 
 by a post-selection.