Update demo, update README.md

.gitignore

@@ -4,4 +4,8 @@ __pycache__/
 .vscode
 
 _/
-TODOs.md
+TODOs.md
+
+demo/on-computable-numbers/output-from-official-app-for-comparison/
+demo/on-computable-numbers/1936\ On\ Computable Numbers\,\ with\ an\ Application\ to\ the\ Entscheidungsproblem\ -\ A\.\ M\.\ Turing/
+demo/on-computable-numbers/1936\ On\ Computable Numbers\,\ with\ an\ Application\ to\ the\ Entscheidungsproblem\ -\ A\.\ M\.\ Turing\ \_remarks.pdf

README.md

@@ -4,38 +4,42 @@ Extract your marks (highlights, scribbles, annotations) and convert them to `Mar
 
 `remarks` works with PDFs annotated on [reMarkable™ paper tablets](https://remarkable.com).
 
-# Overview
+Please note that `remarks` is still highly experimental software. In any case, pull requests are warmly welcome!
+
+## Overview
 
 Highlight and annotate PDFs with your Marker on your reMarkable tablet: 
 
 <!-- How to host images on GitHub but outside your repository? Open an issue, upload your images, and voila! Trick learned from http://felixhayashi.github.io/ReadmeGalleryCreatorForGitHub/ -->
 
 <img width="300" alt="IMG_0642-low.jpg" src="https://user-images.githubusercontent.com/1920195/88480247-3d776680-cf2b-11ea-9c30-061ec0e5cc60.jpg">
 
-Use `remarks` to export annotated pages to `Markdown`, `PDF`, `PNG`, and `SVG` on your computer.
+And then use `remarks` to export annotated pages to `Markdown`, `PDF`, `PNG`, or `SVG` on your computer.
 
----
+`PDF`:
 
-`PNG`:
+- When called with `--targets pdf`, `remarks` outputs a directory with single-page `PDF` files for each annotated page.
+- When called with `--combined_pdf`, `remarks` outputs a all-in-one `PDF` file, merging and replacing the original (unannotated) `PDF` with every one of the annotated pages. 
+- [The annotations in PDF files generated by `remarks` can be read and processed by Zotero](https://github.com/lucasrla/remarks/issues/2#issuecomment-732166093).
 
-<img width="300" alt="demo-remarks-png.png" src="https://user-images.githubusercontent.com/1920195/88480249-410aed80-cf2b-11ea-919b-22fb550ed9d7.png">
+`PNG`:
 
----
+> <img width="300" alt="demo-remarks-png.png" src="https://user-images.githubusercontent.com/1920195/88480249-410aed80-cf2b-11ea-919b-22fb550ed9d7.png">
 
 `Markdown`:
 
-<mark>WHAT IS LIFE?</mark>
-
-Based on lectures delivered under the auspices of the <mark>Dublin Institute for</mark> <mark>Advanced Studies at Trinity College,</mark> Dublin, in February 1943
-
-<mark>To</mark>
-<mark>the memory of My</mark> <mark>Parents</mark>
+> <mark>WHAT IS LIFE?</mark>
+> 
+> Based on lectures delivered under the auspices of the <mark>Dublin Institute for</mark> <mark>Advanced Studies at Trinity College,</mark> Dublin, in February 1943
+> 
+> <mark>To</mark>
+> <mark>the memory of My</mark> <mark>Parents</mark>
 
----
+`SVG`:
 
-# Setup and usage
+- Please note that the `SVG` output includes only the annotations, not the original PDF content.
 
-Please note that `remarks` is still highly experimental software. In any case, pull requests are warmly welcome!
+# Setup
 
 Although I expect `remarks` to be easy to install and use on Linux and Windows, so far it has been used only on a macOS Catalina computer and a ([1st generation](https://remarkable.com/store/remarkable)) reMarkable tablet with software versions `2.2.0.48`, `2.3.0.16`, and `2.4.1.30`.
 
@@ -53,34 +57,52 @@ Alternatively, you can use the good old `scp` to copy files from the tablet to y
 
 - To prevent any unintented interruptions, you can (optionally) switch off the `Auto sleep` feature in `Menu > Settings > Battery` before transferring your files.
 
-
-## 2. Clone, install and run `remarks`
+## 2. Clone this repository and install the dependencies
 
 ```sh
 git clone https://github.com/lucasrla/remarks.git
 
 cd remarks
 
 pyenv virtualenv remarks && pyenv local remarks
-# or your tool of choice for managing environments
+# Or your tool of choice for managing environments
 
 poetry install
-# or your tool of choice for managing dependencies
-# for example:
-# pip install -r requirements.txt
+# Or your tool of choice for managing dependencies (e.g., pip)
 
-# if you use pip, please note that requirements.txt in this repo was created with:
+# pip install -r requirements.txt
+# If you use pip, note that the requirements.txt file was created via:
 # poetry export --without-hashes -f requirements.txt -o requirements.txt
+```
+
+# Usage & Demo
 
-# run the demo
-python -m remarks demo/xochitl demo/output
+Run `remarks` and check out what arguments are available:
 
-# read what additional flags are available
+```sh
 python -m remarks --help
+```
+
+Then, to get a quick and concrete sense of `remarks`, run the demo:
+
+```sh
+# Alan Turing's 1936 foundational paper (with a few highlights and scribbles)
+
+# Original PDF file downloaded from:
+# "On Computable Numbers, with an Application to the Entscheidungsproblem"
+# https://londmathsoc.onlinelibrary.wiley.com/doi/abs/10.1112/plms/s2-42.1.230
+
+python -m remarks demo/on-computable-numbers/xochitl demo/on-computable-numbers --targets png md pdf --combined_pdf
+```
+
+A few other examples:
+
+```sh
+# Assuming your `xochitl` files are at `~/backups/remarkable/xochitl/`
+
+python -m remarks ~/backups/remarkable/xochitl/ example_1/ --ann_type highlights --targets md --combined_pdf
 
-# some other examples
-python -m remarks ~/backups/remarkable/xochitl/ test/ --ann_type highlights --targets md
-python -m remarks ~/backups/remarkable/xochitl/ test/ --ann_type scribbles --targets png
+python -m remarks ~/backups/remarkable/xochitl/ example_2/ --targets png
 ```
 
 # Credits and Acknowledgements

demo/on-computable-numbers/xochitl/d3954b55-8429-4220-a2d5-64f1daab9727.content

@@ -0,0 +1,111 @@
+{
+    "dummyDocument": false,
+    "extraMetadata": {
+        "LastBallpointColor": "Black",
+        "LastBallpointSize": "2",
+        "LastBallpointv2Color": "Black",
+        "LastBallpointv2Size": "2",
+        "LastCalligraphyColor": "Black",
+        "LastCalligraphySize": "2",
+        "LastClearPageColor": "Black",
+        "LastClearPageSize": "2",
+        "LastEraseSectionColor": "Black",
+        "LastEraseSectionSize": "2",
+        "LastEraserColor": "Black",
+        "LastEraserSize": "2",
+        "LastEraserTool": "Eraser",
+        "LastFinelinerColor": "Black",
+        "LastFinelinerSize": "2",
+        "LastFinelinerv2Color": "Black",
+        "LastFinelinerv2Size": "1",
+        "LastHighlighterColor": "Black",
+        "LastHighlighterSize": "2",
+        "LastHighlighterv2Color": "Black",
+        "LastHighlighterv2Size": "2",
+        "LastMarkerColor": "Black",
+        "LastMarkerSize": "2",
+        "LastMarkerv2Color": "Black",
+        "LastMarkerv2Size": "2",
+        "LastPaintbrushColor": "Black",
+        "LastPaintbrushSize": "2",
+        "LastPaintbrushv2Color": "Black",
+        "LastPaintbrushv2Size": "2",
+        "LastPen": "Finelinerv2",
+        "LastPencilColor": "Black",
+        "LastPencilSize": "2",
+        "LastPencilv2Color": "Black",
+        "LastPencilv2Size": "2",
+        "LastReservedPenColor": "Black",
+        "LastReservedPenSize": "2",
+        "LastSelectionToolColor": "Black",
+        "LastSelectionToolSize": "2",
+        "LastSharpPencilColor": "Black",
+        "LastSharpPencilSize": "2",
+        "LastSharpPencilv2Color": "Black",
+        "LastSharpPencilv2Size": "2",
+        "LastSolidPenColor": "Black",
+        "LastSolidPenSize": "2",
+        "LastTool": "Finelinerv2",
+        "LastUndefinedColor": "Black",
+        "LastUndefinedSize": "1",
+        "LastZoomToolColor": "Black",
+        "LastZoomToolSize": "2"
+    },
+    "fileType": "pdf",
+    "fontName": "",
+    "lineHeight": -1,
+    "margins": 100,
+    "orientation": "portrait",
+    "pageCount": 36,
+    "pages": [
+        "bd1287ac-b54f-4024-a117-020194385543",
+        "3e38ed38-08b7-42d2-8bbe-fa8b936b4a45",
+        "30897e20-40af-4ba9-ad23-6a2168d0d1d3",
+        "620fcd75-bfa0-4d8d-a270-bb85286c06b0",
+        "e0beb691-adc3-4b33-b8d3-3097542d724a",
+        "e0e6a63a-cab5-4aeb-8efc-0ae85fa5cd63",
+        "4c88e13b-8714-4b0b-8b9b-09252cff34db",
+        "dbfa49f6-755b-4059-b56e-2af76199c3b2",
+        "a7ee8369-c491-4a09-9f8a-b042a2612133",
+        "2a791213-1f20-42af-8a70-2fa595876a59",
+        "3f55f686-7dfe-4cd3-bc2c-b191087bbe19",
+        "c14e0a28-de19-41e8-a64d-4f05e27f617a",
+        "0e96d028-ac5a-4a03-b833-7257125a3678",
+        "4ac39853-528e-4d4f-97a9-28dfdf379836",
+        "3b3101f3-8f97-415b-9550-95b6834b5933",
+        "9fa5cf25-6498-4cff-a1ba-91bc168cf278",
+        "7dd5c1c1-98d2-4ef0-a493-582b3005c125",
+        "01f774ed-7e04-43ca-8826-d999a3ae946e",
+        "39dff4dd-29bd-4ce1-ba83-3b20cc5ba1b4",
+        "5fdd99fd-e003-4de9-9e72-fee6bd28af2d",
+        "39184354-1c51-4cfc-bd28-2cf9e56bb9b2",
+        "2079430a-1204-49c6-ae38-c098a433accb",
+        "f01b3b49-bee4-4e32-bbb4-40e464e0c563",
+        "5ee7fc59-4246-4bbe-829f-a5645e70a5d1",
+        "17cdcbbb-c348-4465-9e65-4e418d3ef6e4",
+        "7f2dae8a-9b29-4fc3-922d-39e7dcc3f55d",
+        "b828c2ae-235d-4bed-98ce-ea1f9ae6a612",
+        "a8cee983-7203-4218-a1af-e2f4fcf3d073",
+        "d89fa216-a0ca-42fe-b08f-9ca3e36d5685",
+        "12ab3d8f-9f6b-44d2-af26-735bc46cbe74",
+        "3cf8a0af-903f-43e8-880c-4ca7c9baaa1f",
+        "0661c2f6-ee39-461b-a592-1e602ca7e5d1",
+        "d1abf481-8972-4653-8b17-86f265770c88",
+        "656393f6-f005-48de-bb3b-5dd4f14475f2",
+        "042b1bff-1205-4d55-8752-3aa40b4949b5",
+        "601e58ec-7d7e-4820-ab65-a7ea4a674b86"
+    ],
+    "textAlignment": "left",
+    "textScale": 1,
+    "transform": {
+        "m11": 1,
+        "m12": 0,
+        "m13": 0,
+        "m21": 0,
+        "m22": 1,
+        "m23": 0,
+        "m31": 0,
+        "m32": 0,
+        "m33": 1
+    }
+}

demo/on-computable-numbers/xochitl/d3954b55-8429-4220-a2d5-64f1daab9727.metadata

@@ -0,0 +1,13 @@
+{
+    "deleted": false,
+    "lastModified": "1606670817393",
+    "lastOpenedPage": 1,
+    "metadatamodified": false,
+    "modified": false,
+    "parent": "44c5487f-81e3-4765-856a-c3b41630b4a5",
+    "pinned": false,
+    "synced": true,
+    "type": "DocumentType",
+    "version": 4,
+    "visibleName": "1936 On Computable Numbers, with an Application to the Entscheidungsproblem - A. M. Turing"
+}

demo/on-computable-numbers/xochitl/d3954b55-8429-4220-a2d5-64f1daab9727/bd1287ac-b54f-4024-a117-020194385543-metadata.json

@@ -0,0 +1,7 @@
+{
+    "layers": [
+        {
+            "name": "Layer 1"
+        }
+    ]
+}