Readme updates

1 files changed, 67 insertions, 51 deletions

diff --git a/README.md b/README.md
index 8b1db06..341b588 100644
--- a/README.md
+++ b/README.md
@@ -19,10 +19,12 @@ $ p2r https://hbr.org/2019/11/getting-your-team-to-do-more-than-meet-deadlines
 
 The script can be run through the ``p2r`` command line program or via Docker
 (see below). If you're using MacOS, you might be interested in the [Alfred
-workflow](#alfred) or [Printing to p2r](#printing). On Linux, a background
-terminal such as [Guake](http://guake-project.org/) can be very handy. Note 
-that even without a reMarkable, this program can make downloading papers 
-easier (just use the `-n` flag).
+workflow](#alfred-workflow) or [Printing to p2r](#printing). On Linux, a 
+background terminal such as [Guake](http://guake-project.org/) can be very 
+handy. Note that even without a reMarkable, this program can make downloading 
+papers easier (just use the `-n` flag).
+
+## Introduction
 
 ``paper2remarkable`` makes it as easy as possible to get a PDF on your 
 reMarkable from any of the following sources:
@@ -68,43 +70,8 @@ Optionally, you can:
 - Provide an explicit filename using the ``--filename`` parameter
 - Specify the location on the reMarkable to place the file (default ``/``)
 
-Here's the full help of the script:
-
-```
-usage: p2r [-h] [-b] [-c] [-d] [-n] [-p REMARKABLE_DIR] [-r] [-k] [-v] [-V]
-           [--filename FILENAME] [--gs GS] [--pdftoppm PDFTOPPM]
-           [--pdftk PDFTK] [--qpdf QPDF] [--rmapi RMAPI]
-           input
-
-Paper2reMarkable version 0.7.1
-
-positional arguments:
-  input                 URL to a paper or the path of a local PDF file
-
-optional arguments:
-  -h, --help            show this help message and exit
-  -b, --blank           Add a blank page after every page of the PDF
-  -c, --center          Center the PDF on the page, instead of left align
-  -d, --debug           debug mode, doesn't upload to reMarkable
-  -n, --no-upload       don't upload to the reMarkable, save the output in
-                        current working dir
-  -p REMARKABLE_DIR, --remarkable-path REMARKABLE_DIR
-                        directory on reMarkable to put the file (created if
-                        missing, default: /)
-  -r, --right           Right align so the menu doesn't cover it
-  -k, --no-crop         Don't crop the pdf file
-  -v, --verbose         be verbose
-  -V, --version         Show version and exit
-  --filename FILENAME   Filename to use for the file on reMarkable
-  --gs GS               path to gs executable (default: gs)
-  --pdftoppm PDFTOPPM   path to pdftoppm executable (default: pdftoppm)
-  --pdftk PDFTK         path to pdftk executable (default: pdftk)
-  --qpdf QPDF           path to qpdf executable (default: qpdf)
-  --rmapi RMAPI         path to rmapi executable (default: rmapi)
-```
-
-And here's an example with verbose mode enabled that shows everything the 
-script does by default:
+Here's an example with verbose mode enabled that shows everything the script 
+does by default:
 
 ```
 $ p2r -v https://arxiv.org/abs/1811.11242
@@ -132,9 +99,6 @@ The script requires the following external programs to be available:
   manager provides.
 - [GhostScript](https://www.ghostscript.com/)
 - [rMAPI](https://github.com/juruen/rmapi)
-- Optional: [pdftoppm](https://linux.die.net/man/1/pdftoppm) (recommended for 
-  speed). Usually part of a [Poppler](https://poppler.freedesktop.org/) 
-  installation.
 
 Specifically:
 
@@ -162,12 +126,62 @@ Specifically:
    ```
    this installs the ``p2r`` command line program.
 
-If any of the dependencies are not available on the ``PATH`` variable, you can 
-supply them with the relevant options to the script (for instance ``p2r 
---rmapi /path/to/rmapi``). If you run into trouble with the installation, 
-please let me know!
+**Optionally**, you can install:
+
+- [pdftoppm](https://linux.die.net/man/1/pdftoppm) (recommended for speed). 
+  Usually part of a [Poppler](https://poppler.freedesktop.org/) installation.
+
+- the [ReadabiliPy](https://github.com/alan-turing-institute/ReadabiliPy) 
+  package with Node.js support, to allow using 
+  [Readability.js](https://github.com/mozilla/readability) for HTML articles. 
+  This is known to improve the output of certain web articles.
 
-## Alfred
+If any of the dependencies (such as rmapi or ghostscript) are not available on 
+the ``PATH`` variable, you can supply them with the relevant options to the 
+script (for instance ``p2r --rmapi /path/to/rmapi``). If you run into trouble 
+with the installation, please let me know by opening an issue [on 
+Github][github-url].
+
+## Usage
+
+The full help of the script is as follows. Hopefully the various command line 
+flags are self-explanatory, but if you'd like more information, please open an 
+issue [on GitHub][github-url].
+
+```
+usage: p2r [-h] [-b] [-c] [-d] [-n] [-p REMARKABLE_DIR] [-r] [-k] [-v] [-V]
+           [--filename FILENAME] [--gs GS] [--pdftoppm PDFTOPPM]
+           [--pdftk PDFTK] [--qpdf QPDF] [--rmapi RMAPI]
+           input
+
+Paper2reMarkable version 0.7.1
+
+positional arguments:
+  input                 URL to a paper or the path of a local PDF file
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -b, --blank           Add a blank page after every page of the PDF
+  -c, --center          Center the PDF on the page, instead of left align
+  -d, --debug           debug mode, doesn't upload to reMarkable
+  -n, --no-upload       don't upload to the reMarkable, save the output in
+                        current working dir
+  -p REMARKABLE_DIR, --remarkable-path REMARKABLE_DIR
+                        directory on reMarkable to put the file (created if
+                        missing, default: /)
+  -r, --right           Right align so the menu doesn't cover it
+  -k, --no-crop         Don't crop the pdf file
+  -v, --verbose         be verbose
+  -V, --version         Show version and exit
+  --filename FILENAME   Filename to use for the file on reMarkable
+  --gs GS               path to gs executable (default: gs)
+  --pdftoppm PDFTOPPM   path to pdftoppm executable (default: pdftoppm)
+  --pdftk PDFTK         path to pdftk executable (default: pdftk)
+  --qpdf QPDF           path to qpdf executable (default: qpdf)
+  --rmapi RMAPI         path to rmapi executable (default: rmapi)
+```
+
+## Alfred Workflow
 
 On MacOS, you can optionally install [this Alfred workflow][workflow]. Alfred 
 is [a launcher for MacOS](https://www.alfredapp.com/).
@@ -264,5 +278,7 @@ Then you can use ``paper2remarkable`` from the command line as ``p2r``!
 
 License: MIT
 
-If you find a problem or want to suggest a feature, please let us know! You're 
-helping to make this project better!
+If you find a problem or want to suggest a feature, please open an issue [on 
+Github][github-url]. You're helping to make this project better for everyone!
+
+[github-url]: https://github.com/GjjvdBurg/paper2remarkable