search

alphapapa / org-protocol-capture-html

Capture HTML from the browser selection into Emacs as org-mode content
452 stars 39 forks source link

README: add all docs on x-sheme-handles/org-protocol #33

Closed Anton-Latukha closed 4 years ago

Anton-Latukha commented 5 years ago

Docs are partly my contribution, and taken from https://github.com/sprig/org-capture-extension/pull/56

Project licensed MIT, and I contfibuted docs, notified main dev that I am taking the section, and thanked him.

There is more info in upper link, and in my bugreport mentioned in the submitted docs here. I made some research and empirical work to find proper way to register x-sheme-handles/* handlers.

You can observe *this README GitHub-rendered result here: https://github.com/Anton-Latukha/org-protocol-capture-html/tree/add-org-protocol-documentation

alphapapa commented 5 years ago

Hi,

Thanks for the PR. Some of this info may be useful, but it needs some tidying up and editing. There are also some things I'm not sure about:

  1. I'm leery about publishing a Bash script which mangles input to emacsclient. That should be avoided if at all possible. If there are upstream bugs making it necessary, those should be fixed upstream as much as possible.
  2. The contents of necessary .desktop files should be given plainly rather than as shell commands which create them. Copying and pasting shell commands should be discouraged, especially long, multi-line ones, which terminal emulators and shells may not handle well.
Anton-Latukha commented 5 years ago

Please take a note that PR docs are distinguishing between KDE4 kbuildsycoca4 and in fact there is workaround for KDE4 bug, that is not mentioned in your changes to docs. That is written there. If people still use KDE4 - I can not help them but provide what you criticized in 1. Or send them to the thread.

And here is also relevant KDE5 info that uses kbuildsycoca5, that is not in your changes to the docs.

We can go with this PR either way.

alphapapa commented 4 years ago

Reading your last comment again, I'm not sure how it addresses my feedback, so I'm not sure what to do next.

If you can help update outdated information in the readme, that would be great, but it needs to fit with the existing style and content rather than being tacked on at the end.

Anton-Latukha commented 4 years ago

@alphapapa You are right, priorly I was in the stance that I send in useful info, and left the decision to you.

Now I reworked the docs. I merged the duplications of info that are in the upstream version. Now it describes one process from start to finish. I am not the one to drop the old info, like KDE4 info or old Firefox behavior, maybe it is needed for someone, they have accordingly named subsections.

Blocks of code aligned to the start of the line.

Used the fish code blocks for most simple sh blocks. In those simple examples - that is both sh and fish compatible code. Main reason of this - this is documentation and fish marked blocks have a way better highlighting in both Emacs and GitHub.

I've taken the liberty to change the capture template example, preferring hiding metadata (like date link captured on) out of my eyes to look only when it is needed, the example is set to according form.

The whole parsed result.

Anton-Latukha commented 4 years ago

As in #34 it is impossible to merge documentation, it took 1.5 years and no progress, so closing.