1 files changed, 68 insertions, 119 deletions
diff --git a/README.md b/README.md
index 9a00282..3255f4b 100644
--- a/README.md
+++ b/README.md
@@ -1,168 +1,117 @@
 # Pandoc
 
-A watcher and a Mix task that uses Pandoc to convert markdown files to html.
+A watcher and Mix tasks for installing and invoking [pandoc](https://pandoc.org/).
 
 ## Requirements
 
-- inotify-tools
-- pandoc
+Currently only supports `linux-amd64` architectures.
 
 ## Installation
 
-```elixir
-# mix.exs
+If you are going to convert markup in production, then you add `pandoc` as
+dependency on all environments but only start it in dev:
 
+```elixir
 def deps do
   [
-    {:pandoc, "~> 0.2.0", runtime: Mix.env() == :dev}
+    {:pandoc, "~> 0.3", runtime: Mix.env() == :dev}
   ]
 end
 ```
 
-## Use
+However, if your markup is preconverted during development, then it only needs
+to be a dev dependency:
 
 ```elixir
-# mix.exs
-
-# ...
-defp aliases do
+def deps do
   [
-    # ...
-    "documents.build": ["pandoc hello"],
-    "statics.build": ["assets.build", "documents.build"],
-    "statics.deploy": ["assets.deploy", "documents.build"]
+    {:pandoc, "~> 0.3", only: :dev}
   ]
 end
 ```
 
-```elixir
-# config/config.exs
-
-config :pandoc,
-  hello: [
-    args: ~w(--mathjax -o ../priv/static/posts),
-    cd: Path.expand("../documents", __DIR__)
-  ]
-```
+Once installed, change your `config/config.exs` to pick your pandoc version of
+choice:
 
 ```elixir
-# config/dev.exs
-
-config :hello, HelloWeb.Endpoint,
-  # ...
-  watchers: [
-    # ...
-    pandoc: {Pandoc, :run, [:hello, ~w(--watch)]}
-  ]
-
-config :pandoc, hello: [pattern: "**/*.md"]
+config :pandoc, version: "3.6.1"
 ```
 
-```elixir
-# lib/hello_web/router.ex
-
-  scope "/", HelloWeb do
-    pipe_through :browser
+Now you can install pandoc by running:
 
-    get "/drafts/:id", PostController, :draft
-    get "/posts/:id", PostController, :show
-    get "/posts", PostController, :index
-
-    get "/", PageController, :home
-  end
+```bash
+$ mix pandoc.install
 ```
 
-```elixir
-# lib/hello_web/controllers/posts_controller.ex
-
-defmodule HelloWeb.PostController do
-  use HelloWeb, :controller
+And invoke pandoc with:
 
-  alias Hello.Document
-  @path "documents/**/*.md"
-  paths = Path.wildcard(@path)
-  @paths_hash :erlang.md5(paths)
-  for path <- paths, do: @external_resource(path)
-  @posts Document.list()
+```bash
+$ mix pandoc default documents/hello.md -o priv/static/posts/hello.html
+```
 
-  def __mix_recompile__?(), do: @path |> Path.wildcard() |> :erlang.md5() != @paths_hash
+The executable is kept at `_build/pandoc-TARGET`. Where `TARGET` is your
+system target architecture.
 
-  def index(conn, _params) do
-    render(conn, :index, posts: @posts)
-  end
+## Profiles
 
-  def show(conn, %{"id" => id}) do
-    assigns = [
-      post: :hello |> :code.priv_dir() |> Path.join("static/posts/#{id}.html") |> File.read!()
-    ]
+The first argument to `pandoc` is the execution profile. You can define multiple
+execution profiles with the current directory, the OS environment, and default
+arguments to the `pandoc` task:
 
-    render(conn, :show, assigns)
-  end
+```elixir
+config :pandoc,
+  version: "3.6.1",
+  default: [
+    args: ~w(--mathjax),
+    cd: Path.expand("../documents", __DIR__)
+  ]
+```
 
-  def drafts(conn, %{"id" => id}) do
-    config = Application.get_env(:pandoc, :hello)
+When `mix pandoc default` is invoked, the task arguments will be appended to
+the ones configured above. Note profiles must be configured in your
+`config/config.exs`, as `pandoc` runs without starting your application (and
+therefore it won't pick settings in `config/runtime.exs`).
 
-    opts = [
-      cd: config[:cd] || File.cwd!()
-    ]
+## Adding to Phoenix
 
-    filename = List.keyfind(@posts, id, 0) |> elem(1) |> Map.get(:filename)
-    path = Path.join("_drafts", filename)
+To add `pandoc` to an application using Phoenix, you will need Phoenix v1.6+ and
+the following steps.
 
-    render(conn, :show, post: "pandoc" |> System.cmd([path], opts) |> elem(0))
-  end
-```
+First add it as a dependency in your `mix.exs`:
 
 ```elixir
-# lib/hello/document.ex
-
-defmodule Stasis.Document do
-  require Logger
-
-  @ext ".md"
-  @pattern Application.compile_env(:pandoc, [:hello, :pattern])
-
-  def list() do
-    "documents"
-    |> Path.join(@pattern)
-    |> Path.wildcard()
-    |> Enum.map(fn path -> {Path.basename(path), path} end)
-    |> Enum.sort(fn {basename_a, _}, {basename_b, _} -> basename_a < basename_b end)
-    |> Enum.reduce([], fn {filename, path}, acc ->
-      id = Path.rootname(filename, @ext)
-      data = if "_drafts" in Path.split(path), do: %{:draft, true}, else: %{}
-
-      [{id, data} | acc]
-    end)
-  end
+def deps do
+  [
+    {:phoenix, "~> 1.6"},
+    {:pandoc, "~> 0.3", runtime: Mix.env() == :dev}
+  ]
+end
 ```
 
-```elixir
-# lib/hello_web/controllers/post_html.ex
-
-# ...
-
-defp href(filename, draft \\ false) do
-  root = (draft && "/drafts") || "/posts"
-  Path.join(root, filename |> Path.basename(".md"))
-end
+Now let's change `config/config.exs` to configure `pandoc` to write to
+`priv/static/posts`:
 
+```elixir
+config :pandoc,
+  version: "3.6.1",
+  default: [
+    args: fn extra_args ->
+      {_, [input_file], _} = OptionParser.parse(extra_args, switches: [])
+      ~w(--output=../priv/static/posts/#{Path.rootname(input_file)}.html)
+    end,
+    cd: Path.expand("../documents", __DIR__)
+  ]
 ```
 
-```heex
-<!-- lib/hello_web/controllers/post_html/index.html.heex -->
+For development, we want to enable the watcher. So find the `watchers`
+configuration in your `config/dev.exs` and add:
 
-<%= for {id, data} <- @posts do %>
-  <p>
-    <.link href={href(Path.rootname(filename), data[:draft])} method="get">
-      <%= id %>
-    </.link>
-  </p>
-<% end %>
+```elixir
+pandoc: {Pandoc, :watch, [:default]}
 ```
 
-```heex
-<!-- lib/hello_web/controllers/post_html/show.html.heex -->
+Note we are enabling the file system watcher.
 
-<%= raw(@post) %>
-```
+## Licence
+
+pandoc source code is licensed under the MIT License.