From f7b0d75f8c5361be9b55c7a1c8f042cf24c01e10 Mon Sep 17 00:00:00 2001 From: Sam Strachan Date: Sat, 10 Dec 2022 12:42:37 +0000 Subject: [PATCH] Documentation update (#490) * Documentation update Documentation for #489 and #483 --- docs/config.md | 33 +++++++++++++++++++------ docs/install.md | 12 +++++++++ docs/integration.md | 59 +++++++++++++++++++++------------------------ 3 files changed, 65 insertions(+), 39 deletions(-) diff --git a/docs/config.md b/docs/config.md index c0af8b0f..35fceaff 100644 --- a/docs/config.md +++ b/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.} + */ + async afterScan(fileInfo) { + // Copy the scan to my home directory + return await Process.spawn(`cp '${fileInfo.fullname}' ~/`); + } }; ``` diff --git a/docs/install.md b/docs/install.md index adfda673..9742dbc1 100644 --- a/docs/install.md +++ b/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` diff --git a/docs/integration.md b/docs/integration.md index e02f00ef..92ad380a 100644 --- a/docs/integration.md +++ b/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.} + */ + 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@address.tld)', - 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@address.tld`, - '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.} + */ + async afterScan(fileInfo) { + return await Process.spawn(`mpack -s "Document from Scanner@Office" "${fileInfo.fullname}" email@address.tld`); } -}); ``` -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@address.tld -``` - -This sets a time-based filename, then OCRs and finally sends to -email@address.tld - ## Other recipes? If you have other recipes then please share them.