Documentation update (#490)

* Documentation update

Documentation for #489 and #483

docs/config.md

@@ -1,18 +1,24 @@
-# Configuration overrides
+# Configuration and integration
 
 Sometimes scanners don't return quite what you want them to. Likewise, perhaps
-scanservjs doesn't provide the defaults you want. Furtunately it's possible to
-override most things you might want to.
+scanservjs doesn't provide the defaults you want. And maybe you want to do your
+own thing after a scan. Furtunately it's possible to override most things you
+might want to.
 
-The two things you can modify are:
-* `config`: These are the global settings which include things like:
+There are three hooks where you can customise behaviour:
+* `afterConfig`: This provides a reference to the config where you can apply
+  your own changes to global settings which include things like:
   * Server port
   * Log level
   * Preview resolution
   * Output filename
   * Pipelines (output format)
-* `devices`: The device definitions which are reported by SANE which include
-  scanner dimensions and geometry, modes, resolutions and sources.
+* `afterDevices`: You can alter the device definitions which are reported by
+  SANE which include scanner dimensions and geometry, modes, resolutions and
+  sources.
+* `afterScan`: You receive a reference to the file which has just been scanned;
+  copy it somewhere, call a script or write some code.
+
 
 TL;DR; copy `./config/config.default.js` to `config/config.local.js`, override
 the sections you want and then restart the app
@@ -24,11 +30,13 @@ e.g. `-v /my/local/path:/app/config`.
 ## How it works
 
 scanservjs looks for a file called `config/config.local.js` and attempts to call
-two functions at different stages in the processing:
+three functions at different stages in the processing:
 * `afterConfig(config)`: whenever a config is read, the result is passed to this
   function before being either used or sent down to the browser.
 * `afterDevices(devices)`: whenever the devices are read, the result is passed
   to this function before being used.
+* `afterScan(fileInfo)`: whenever a scan completes, the resultant file is passed
+  to this function.
 * See [example source](../packages/server/config/config.default.js) for more
   options.
 * Please note that the config file only gets read at start-up - so if you make
@@ -75,6 +83,15 @@ module.exports = {
         device.features['-y'].default = 297;  
       });
   }
+
+  /**
+   * @param {FileInfo} fileInfo 
+   * @returns {Promise.<Buffer>}
+   */
+  async afterScan(fileInfo) {
+    // Copy the scan to my home directory
+    return await Process.spawn(`cp '${fileInfo.fullname}' ~/`);
+  }
 };
 ```
 

docs/install.md

@@ -34,6 +34,18 @@ rm scanservjs.tar.gz
 rm -r scanservjs
 ```
 
+## Uninstall
+
+To uninstall, just run `sudo /var/www/scanservjs/installer.sh -u`.
+
+* You need root privileges - hence `sudo`
+* When you run with no arguments, it will just
+  [print the help](https://github.com/sbs20/scanservjs/blob/e4ce5f0de13a23c3050ddd7e58dedb790c9fa4d4/packages/server/installer.sh#L188)
+* You can read the script to see what it does
+* There are actually two uninstall options `-u` (safe and fine) and
+  `--force-uninstall`, which will also remove dependencies, which is a bit more
+  risky. Again, see the script source to decide for yourself.
+
 ## Troubleshooting
 
 Scanservjs works by wrapping CLI calls to `scanimage` as the user `scanservjs`

docs/integration.md

@@ -48,18 +48,14 @@ directory itself and use either inotify or cron. If you want to embed into the
 pipeline then something like the following may help:
 
 ```javascript
-config.pipelines.push({
-  extension: 'pdf',
-  description: 'PDF | Scan2Cloud ⇒ Your_Configured_Provider_or_Remote ',
-  get commands() {
-    return [
-      'convert @- -quality 92 tmp-%04d.jpg && ls tmp-*.jpg',
-      'convert @- scan-0000.pdf',
-      `rclone copy scan-0000.pdf YOUR_PROVIDER:/path/to/folder`,
-      'ls scan-*.*'
-    ];
+  /**
+   * @param {FileInfo} fileInfo 
+   * @returns {Promise.<Buffer>}
+   */
+  async afterScan(fileInfo) {
+    // Copy the scan to my home directory
+    return await Process.spawn(`rclone copy '${fileInfo.fullname}' YOUR_PROVIDER:/path/to/folder`);
   }
-});
 ```
 
 ## Scan2Mail
@@ -75,29 +71,30 @@ config.pipelines.push({
 Now create the following pipeline in your `config/config.local.js`
 
 ```javascript
-config.pipelines.push({
-  extension: 'pdf',
-  description: 'ocrmypdf (Scan2Mail [email protected])',
-  get commands() {
-    return [
-      'convert @- -quality 92 tmp-%04d.jpg && ls tmp-*.jpg',
-      'convert @- pdf:-',
-      `file="scan_$(date +"%d_%m_%Y-%H_%M").pdf" && ocrmypdf -l ${config.ocrLanguage} --deskew --rotate-pages --force-ocr - "$file" && mpack -s "Document from Scanner@Office" "$file" [email protected]`,
-      'ls scan_*.*'
-    ];
+  afterConfig(config) {
+    config.pipelines.push({
+      extension: 'pdf',
+      description: 'ocrmypdf',
+      get commands() {
+        return [
+          'convert @- -quality 92 tmp-%04d.jpg && ls tmp-*.jpg',
+          'convert @- pdf:-',
+          `ocrmypdf -l ${config.ocrLanguage} --deskew --rotate-pages --force-ocr - "scan_0.pdf"`,
+          'ls scan_*.*'
+        ];
+      }
+    });
+  },
+
+  /**
+   * @param {FileInfo} fileInfo 
+   * @returns {Promise.<Buffer>}
+   */
+  async afterScan(fileInfo) {
+    return await Process.spawn(`mpack -s "Document from Scanner@Office" "${fileInfo.fullname}" [email protected]`);
   }
-});
 ```
 
-The important `Scan2Mail` line is:
-
-```
-file="scan_$(date +"%d_%m_%Y-%H_%M").pdf" && ocrmypdf -l ${config.ocrLanguage} --deskew --rotate-pages --force-ocr - "$file" && mpack -s "Document from Scanner@Office" "$file" [email protected]
-```
-
-This sets a time-based filename, then OCRs and finally sends to
-[email protected]
-
 ## Other recipes?
 
 If you have other recipes then please share them.