aynish/grasp
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

Update readme

Browse source
This commit is contained in:
Dima Gerasimov 2019-01-27 10:06:14 +00:00
parent 76cd14a44c
commit 0943ab4966
2 changed files with 23 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

35
README.md
View file

@ -1,14 +1,19 @@
Build status: [![CircleCI](https://circleci.com/gh/karlicoss/grasp.svg?style=svg)](https://circleci.com/gh/karlicoss/grasp) Build status: [![CircleCI](https://circleci.com/gh/karlicoss/grasp.svg?style=svg)](https://circleci.com/gh/karlicoss/grasp)
Grasp is an [extension for Chrome](https://chrome.google.com/webstore/detail/grasp-extension/ohhbcfjmnbmgkajljopdjcaokbpgbgfa) (Firefox support is in progress), which adds a button/keybinding to capture current page title and url, Grasp is an [extension for Chrome](https://chrome.google.com/webstore/detail/org-grasp/ohhbcfjmnbmgkajljopdjcaokbpgbgfa) (Firefox support is in progress), which adds a button/keybinding to capture current page title and url,
possibly selected text, additional comments or tags and send it into your [Org Mode](https://orgmode.org/) file. possibly selected text, additional comments or tags and adds it into your [Org Mode](https://orgmode.org/) file.
[See a short demo](https://www.youtube.com/watch?v=Z8Bk-IazdGo). [See a short demo](https://www.youtube.com/watch?v=Z8Bk-IazdGo).
# Requirements Install from Chrome store:
No third party dependencies! Just `python 3.6`.
* [localhost only version](https://chrome.google.com/webstore/detail/org-grasp/ohhbcfjmnbmgkajljopdjcaokbpgbgfa)
* [any host version](https://chrome.google.com/webstore/detail/org-grasp-any-host/gcfhlnaalomahoampfjhinmgjikkkgep) (the only difference are permissions in manifest)
# Running # Running
In the simplest setup, the server runs locally, and you can use 'localhost' version of the extension. If you have to work on a computer where you can't run python scripts,
or your target capture file is just not there, you can selfhost the server part elsewhere and use the 'any host' version. Don't forget to set the endpoint in extension settings!
1. Install server counterpart as systemd service (to autostart it): `server/setup --path /path/to/your/capture.org [--port <custom port>] [--template <custom org-capture template>]`. 1. Install server counterpart as systemd service (to autostart it): `server/setup --path /path/to/your/capture.org [--port <custom port>] [--template <custom org-capture template>]`.
Or alternatively, just run it directly if you don't want to autostart it: `server/grasp_server.py --path /path/to/your/capture.org [--port <custom_port>] [--template <custom org-capture template>]`. Or alternatively, just run it directly if you don't want to autostart it: `server/grasp_server.py --path /path/to/your/capture.org [--port <custom_port>] [--template <custom org-capture template>]`.
@ -16,26 +21,30 @@ No third party dependencies! Just `python 3.6`.
That's it! If you're using custom port make sure it's same as in the extension settings (default is `12212`). That's it! If you're using custom port make sure it's same as in the extension settings (default is `12212`).
## Using arbitrary endpoint instead of localhost
If you want to run the server remotely, you need extra permissions. Chrome store requires some extra checks when publishing if you do that, so I figured it's better to have localhost only by default. You can use unrestricted extension instead and connect to the remote host. Ssee `grasp-anyhost` packages [here](https://github.com/karlicoss/grasp/releases), or 'Building' section if you'd rather build it yourself. Don't forget to set the endpoint in extension settings!
# Motivation # Motivation
Why use org-capture? Well, it's hard to explain, maybe some other time... However if you do know you want to use it instead/alongside your browser bookmarks, by default Why use org-capture? Well, it's hard to explain, maybe some other time... However if you do know you want to use it instead/alongside your browser bookmarks, by default
you don't have much choice and have to copy everything manually. For an average Org Mode user it's a torture. you don't have much choice and have to copy everything manually. For an experienced enough Org Mode user it's a torture.
For a while, I used [the only](https://github.com/sprig/org-capture-extension) Chrome extension for that (as for January 2019). However, it relies on setting up MIME For a while, I used [the only](https://github.com/sprig/org-capture-extension) Chrome extension for that (as for January 2019). However, it relies on setting up MIME
handler which is quite flaky for many people. What is more, capturing via org template requires always running emacs daemon, which might be too much for some people. handler which is quite flaky for many people (me included). What is more, capturing via org template requires always running emacs daemon, which might be too much for some people.
But the worst thing is if capturing fails, you have to way of knowing about it. After losing few days of captured stuff due to MIME handler mysteriously not working, But the worst thing is if capturing fails, you have to way of knowing about it. After losing few days of captured stuff due to MIME handler mysteriously not working,
I got fed up and figured it's time to implement something more reliable. I got fed up and figured it's time to implement something more reliable.
My approach still requires a running server, but it's a simple python script which simply appends a text entry to a text file. The backend always responds back and in case anything My approach still requires a running server, but it's a simple python script which simply appends a text entry to a text file. The backend always responds back and in case anything
fails, you get a notification. fails, you get a notification.
There is a collateral benefit though is that you can potentially use anything as a backend and storage file, e.g. you might be more of a Markdown or Todo.txt fan (let me know if you are interested in that!).
Main feature of this extension is that you can also add a comment and tags to the information you are capturing.
The only downside so far is that it's not as well integrated with emacs as its builtin capture templates. E.g. currently you can't point at a specific header in org file, it would just append at the end.
However, if that's a stopper for you, please let me know, I could come up with something!
# Requirements
No third party dependencies! Just `python 3.6`.
Extra collateral benefit is that you can potentially add anything as a backend, e.g. you might be more of a Markdown or Todo.txt fan (let me know if you are interested in that!).
# Potentional improvements # Potentional improvements
* due to server counterpart, one could even run it elsewhere, not necessarily on localhost * see [todos](./TODO.org)
* also see [todos](./TODO.org)
# Building extension # Building extension
The most up-to-date instructions should be in [CI config](./.circleci/config.yml). The most up-to-date instructions should be in [CI config](./.circleci/config.yml).
@ -47,7 +56,7 @@ You're gonna need `npm` for building extension.
After that you can find the extension in `build` directory and 'Load unpacked** if necessary. There is also Flow and Eslint set up. After that you can find the extension in `build` directory and 'Load unpacked** if necessary. There is also Flow and Eslint set up.
## Unrestricted url ## building any host version
If you do need unresticted url permissions, build the extensions like that: `ANY_URL=yes npm run build`. If you do need unresticted url permissions, build the extensions like that: `ANY_URL=yes npm run build`.
# Permissions used # Permissions used

1
TODO.org
View file

@ -1,3 +1,4 @@
* TODO [#A] simple auth for server bit?
* TODO [#B] doesn't look like hotkey working unless you manually rebind.. wtf? * TODO [#B] doesn't look like hotkey working unless you manually rebind.. wtf?
* TODO [#C] how to test it? try on different pages? * TODO [#C] how to test it? try on different pages?