fix README and cabal

2 files changed, 85 insertions, 11 deletions

diff --git a/README.md b/README.md
index b3d5d32..08e699c 100644
--- a/README.md
+++ b/README.md
@@ -1,21 +1,94 @@
 
 # reploy
 
-A redo of deployment of the R3 sites (cards for now).
+A complete REdo of dePLOYment of the R3 sites.
+
+This is basically a small heap of haskell that produces a static HTML site out
+of a pile of markdown pages (with metadata in the YAML header blocks, similarly
+to what Jekyll does), complemented with a template and assets. The template
+language here is a slightly updated
+[Mustache](https://en.wikipedia.org/wiki/Mustache_%28template_system%29).
 
 ## How to use this
 
-- install haskell platform (e.g. with https://www.haskell.org/ghcup/)
-- `cabal run site -- --help` shows options
-- `cabal run site` builds a demo site
-- `cabal install` produces and installs an executable `site` into the cabal
-  path (you can use it as a program directly)
+- install the haskell platform (e.g. with https://www.haskell.org/ghcup/)
+- `cabal run reploy` builds a really tiny demo site (run in project folder)
+- `cabal install` produces and installs an executable `reploy` into the cabal
+  path (usually `~/.cabal/bin`) -- you can use it as a program directly
+
+Optionally, there is a docker built directly from this repository.
 
-## Containerized use
+### Containerized use
 
-Docker has insurmountable issues with producing the files with the right
-permissions. Use `podman` instead:
+Locally, Docker has insurmountable issues with producing the files with the
+right permissions. Use `podman` instead, roughly like this:
 
 ```
-podman run -ti --rm -v $PWD:/data gitlab.lcsb.uni.lu:4567/r3/websites-dev/reploy
+podman run -ti --rm -v $PWD:/data gitlab.lcsb.uni.lu:4567/lcsb/sps/reploy -d /data
 ```
+
+## Configuration and options
+
+Run `cabal run reploy -- --help` (or just `reploy --help` if you installed the
+executable) to get a complete listing of available options with the
+documentation.
+
+Generally, you will mostly need to set only `-s` (marks which directories to
+source), `-d` (marks where to put the generated HTML) and `-u` (sets the URL
+base in case your website won't sit in the domain root).
+
+### Search support
+
+Reploy can generate a plaintext JSON dump of the site that is usable with
+Javascript search engines, such as [lunr](https://lunrjs.com/).
+
+The way to produce the search indexes for lunr is described in the
+documentation at the top of `scripts/make-search-index.js`. By default, this
+works with the minimal search implementation present in the default template
+(present in `assets/`, `templates/` and `pages/search.md`)
+
+### YAML options in page markdown
+
+##### Required options
+
+- `mount` (string): what should be the canonical URL of the page
+- `title` (string): the name of the page for display in templates and page links
+
+##### Optional
+
+- `template` (string): name of the template file used to render the page.
+  Defaulted from command options.
+- `search` (boolean, default `true`): if not set, the page is omitted from the
+  search index.
+- `toc` (boolean or int, default `3`): if false, no ToC is generated for the
+  page. Otherwise the integer sets the depth of the ToC.
+- `timestamp` (string): A description of the "timestamp" for the page,
+  typically the date of the last page modification. For any file, this value is
+  also defaulted from `<filename>.timestamp` (e.g., `mypage.md.timestamp`),
+  which simplifies generation of the timestamps by external software (see
+  `scripts/source-timestamps.sh` for an example of how to do that from `git`
+  history)
+- `tags` (array of strings): list of `/`-separated hierarchical tags
+  ("categories") that are assigned to the page. The page will be listed in the
+  category listings accordingly.
+- `redirect` (array of strings): list of mounts that should redirect to this
+  page (useful e.g. for old URLs, etc).
+
+### Template syntax
+
+Reploy uses the "simple" vanilla
+[Mustache](http://mustache.github.io/mustache.5.html) enhanced by a single
+extra construction: `{{?something}}xxx{{/something}}` will render `xxx` only if
+`something` evaluates to "not falsey" (non-null, nonempty). This provides an
+easy but precise way to switch 2 branches of the code given the availability of
+some information in the base data, without any dependence on javascript
+implementation of negated truthiness -- the switch is perfectly complementary
+to `{{^something}}xxx{{/something}}` which only renders `xxx` if `something`
+js-evaluates to falsey (null, empty) value.
+
+Other constructions:
+- `{{#something}}...{{/something}}` can be used to "enter" the scope of
+  something or unpack an array
+- `{{> template.html}}` sources another template in the place
+- `{{{something}}}` renders something WITHOUT escaping the HTML special
+  characters (thus allowing injection of HTML code directly)
diff --git a/reploy.cabal b/reploy.cabal
index e79fe95..12a123a 100644
--- a/reploy.cabal
+++ b/reploy.cabal
@@ -1,9 +1,10 @@
+cabal-version:      3.0
+
 name:               reploy
 synopsis:           Straightforward static all-in-one website builder
 category:           Web
 version:            0.2.0.0
 build-type:         Simple
-cabal-version:      3.0
 license:            Apache-2.0
 license-file:       LICENSE