docs and build shit

README.md

@@ -3,22 +3,78 @@
 [![Package Version](https://img.shields.io/hexpm/v/luma_markdown)](https://hex.pm/packages/luma_markdown)
 [![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/luma_markdown/)
 
+`luma_markdown` converts Luma markup to Markdown. It can read a file or consume
+all of its input from standard input.
+
+## Standalone executable
+
+Gleam can package the Erlang version of the program as an escript. An escript
+is one executable file containing the compiled program and its dependencies
+(it does require Erlang to be installed on the machine where it is run).
+
+From the project directory, run:
+
 ```sh
-gleam add luma_markdown@1
-```
-```gleam
-import luma_markdown
-
-pub fn main() -> Nil {
-  // TODO: An example of the project in use
-}
+gleam export escript
+chmod +x luma_markdown
 ```
 
-Further documentation can be found at <https://hexdocs.pm/luma_markdown>.
+This creates the single executable `./luma_markdown`. Re-run the export
+command after changing the source. To use a different filename, rename the
+generated file:
+
+```sh
+mv luma_markdown luma-md
+```
+
+Pass a file path as the only argument:
+
+```sh
+./luma_markdown input.luma
+```
+
+Or pipe content into it. The command receiving the pipe must come last:
+
+```sh
+echo "#1 A heading" | ./luma_markdown
+cat input.luma | ./luma_markdown
+```
+
+When using a shell with history expansion (such as interactive zsh), use
+single quotes or `printf` for input beginning with `!`:
+
+```sh
+printf '%s\n' '!4 emphasized text' | ./luma_markdown
+```
+
+With no arguments, the executable reads until standard input reaches EOF and
+writes the resulting Markdown to standard output.
+
+## Neovim preview
+
+The working preview configuration is also included in
+[`examples/neovim_luma_preview.lua`](examples/neovim_luma_preview.lua). Copy it
+into your Neovim configuration or source it with:
+
+```lua
+dofile(vim.fn.getcwd() .. "/examples/neovim_luma_preview.lua")
+```
+
+The snippet looks for `luma_markdown` on `PATH`. To use the executable in this
+repository directly, set its path before starting Neovim:
+
+```sh
+export LUMA_MARKDOWN_BIN="$PWD/luma_markdown"
+```
+
+It registers the `:LumaPreview` command and automatically refreshes the
+preview for `*.luma` files.
 
 ## Development
 
 ```sh
-gleam run   # Run the project
-gleam test  # Run the tests
+gleam run -- input.luma  # Run from the Gleam toolchain
+gleam test               # Run the tests
 ```
+
+Further documentation can be found at <https://hexdocs.pm/luma_markdown>.