improve README

n0isiv · Aug 24, 2016 · a75e657 · a75e657
1 parent f7412c9
commit a75e657
Showing 1 changed file with 52 additions and 26 deletions.
diff --git a/README.md b/README.md
@@ -2,30 +2,37 @@
 
 A wrapper for wkhtmltopdf (HTML to PDF) and PDFTK (adds in encryption) for use in Elixir projects. If available, it will use xvfb-run (x virtual frame buffer) to use wkhtmltopdf on systems that have no X installed, e.g. a server.
 
-# New in 0.3.2 and 0.3.3
+# New in 0.3.4
 
-  - 0.3.3
-    -BUGFIX: typo in config/prod.exs
-  - 0.3.2
-    - support for command prefixes, most notably **xvfb-run** to let a
-      wkhtmltopdf which was compiled without an unpatched version of qt run on
-      machines without an x server
-    - (add in precompiled, patched binaries for wkhtmltopdf and libjpeg8 that are
-      needed to run wkhtmltopdf without xvfb-run)
+  - 0.3.4
+    - BUGFIX: fix merge confusion to **realy** support `xvfb-run` or other
+      command prefixes to wkhtmltopdf
+    - support explicit deletion of temporary files thanks to
+      [Edipo Vinicius da Silva](https://github.com/edipox)
+    - Improve README
 
 For a proper changelog, see [CHANGES](CHANGES.md)
 
-# Usage
+# System prerequisites
+
+Download wkhtmltopdf and place it in your $PATH. Current binaries can be found
+here: http://wkhtmltopdf.org/downloads.html
 
-Download wkhtmltopdf and place it in your $PATH. Current binaries can be found here:
-http://wkhtmltopdf.org/downloads.html
+_(optional)_ To use wkhtmltopdf on systems without an X window server installed,
+please install `xvfb-run` from your repository (on Debian/Ubuntu: `sudo apt-get
+install xvfb`).
 
-_(optional)_ To use wkhtmltopdf on systems without an X window server installed, please install `xvfb-run` from your repository or via `homebrew` (Mac)
+On current (2016) Macintosh computers `/usr/X11/bin/xvfb` should be available
+and is reported to do the same thing. _warning:_ This is untested. PLS report to
+me if you ran this successfully on a Mac.
 
-_(optional)_ For best results, download goon and place it in your $PATH. Current binaries can be found here:
-https://github.com/alco/goon/releases
+_(optional)_ For best results, download goon and place it in your $PATH. Current
+binaries can be found here: https://github.com/alco/goon/releases
 
-_(optional)_ Install pdftk (optional) via your package manager or homebrew. The project page also contains a Windows installer
+_(optional)_ Install pdftk (optional) via your package manager or homebrew. The
+project page also contains a Windows installer
+
+# Usage
 
 Add this to your dependencies in your mix.exs:
 
@@ -54,26 +61,45 @@ html = "<html><body><p>Hi there!</p></body></html>"
 { :ok, pdf_content } = File.read file_name 
 ```
 
-# Configuration
+# Options and Configuration
 
 This module will automatically try to finde both `wkhtmltopdf` and `pdftk` in
 your path. But you may override or explicitly set their paths in your
-config/config.exs:
+`config/config.exs`. 
 
 ```
 config :pdf_generator,
     wkhtml_path:    "/usr/bin/wkhtmltopdf",
-    pdftk_path:     "/usr/bin/pdftk",
-    command_prefix: "xvfb-run"
+    pdftk_path:     "/usr/bin/pdftk"
+```
+
+## Running headless (server-mode)
+
+If you happen to want to run an wkhtmltopdf with an unpatched version of webkit
+that requires an X Window server - but on your server (or Mac) ain't one, you
+might find a `command_prefix` handy:
+
+```
+PdfGenerator.generate "<html..", command_prefix: "xvfb-run" 
 ```
 
+This can also be configured globally in cour `config/config.exs`:
+
+```
+config :pdf_generator,
+    command_prefix: "/usr/bin/xvfb-run"
+```
+
+## More options
+
+- `page_size`:        defaults to `A4`, see wkhtmltopdf for more options 
+- `open_password`:    requires `pdftk`, password to encrypt PDFs with
+- `edit_password`:    requires `pdftk`, sets password for edit permissions on PDF
+- `shell_params`:     pass custom parameters to wkhtmltopdf. **CAUTION: BEWARE OF SHELL INJECTIONS!** 
+- `command_prefix`:   see "Running headless" above
+- `delete_temporary`: immediately remove temp files after generation
+
 # Documentation
 
 For more info, read the [docs on hex](http://hexdocs.pm/pdf_generator) or issue
 `h PdfGenerator` in your iex shell.
-
-TODO
-====
-
-- [ ] Pass some useful base path so wkhtmltopdf can resolve static files
-  (styles, images etc) linked in the HTML