Add documentation about how to write userscripts.

Closes #450.
This commit is contained in:
Florian Bruhin 2015-03-10 23:22:53 +01:00
parent acc33b4f91
commit 2b06d4e684
4 changed files with 67 additions and 0 deletions

View File

@ -49,6 +49,7 @@ image:http://qutebrowser.org/img/cheatsheet-small.png["qutebrowser keybinding ch
* link:doc/HACKING.asciidoc[HACKING]
* link:doc/INSTALL.asciidoc[INSTALL]
* link:doc/stacktrace.asciidoc[Reporting segfaults]
* link:doc/userscripts.asciidoc[How to write userscripts]
Getting help
------------

View File

@ -10,6 +10,7 @@ The following help pages are currently available:
* link:FAQ.html[Frequently asked questions]
* link:commands.html[Documentation of commands]
* link:settings.html[Documentation of settings]
* link:userscripts.html[How to write userscripts]
Getting help
------------

64
doc/userscripts.asciidoc Normal file
View File

@ -0,0 +1,64 @@
Writing qutebrowser userscripts
===============================
The Compiler <mail@qutebrowser.org>
qutebrowser is extensible by writing userscripts which can be called via the
`:spawn --userscript` command, or via a keybinding.
These userscripts are similiar to the (non-javascript) dwb userscripts. They
can be written in any language which can read environment variables and write
to a FIFO.
Note for simple things such as opening the current page with another browser or
mpv, a simple keybinding to something like `:spawn mpv {url}` should suffice.
Also note userscripts need to have the executable bit set (`chmod +x`) for
qutebrowser to run them.
Getting information
-------------------
The following environment variables will be set when an userscript is launched:
- `QUTE_MODE`: Either `hints` (started via hints) or `command` (started via
command or keybinding).
- `QUTE_USER_AGENT`: The currently set user agent.
- `QUTE_FIFO`: The FIFO or file to write commands to.
In `command` mode:
- `QUTE_URL`: The current URL.
- `QUTE_TITLE`: The title of the current page.
- `QUTE_SELECTED_TEXT`: The text currently selected on the page.
- `QUTE_SELECTED_HTML` The HTML currently selected on the page.
In `hints` mode:
- `QUTE_URL`: The URL selected via hints.
- `QUTE_SELECTED_TEXT`: The plain text of the element selected via hints.
- `QUTE_SELECTED_HTML` The HTML of the element selected via hints.
Sending commands
----------------
Normal qutebrowser commands can be written to `$QUTE_FIFO` and will be
executed.
On Unix/OS X, this is a named pipe and commands written to it will get executed
immediately.
On Windows, this is a regular file, and the commands in it will be executed as
soon as your userscript terminates. This means when writing multiple commands,
you should append to the file (`>>` in bash) rather than overwrite it (`>`).
Examples
--------
Opening the currently selected word on http://www.dict.cc/[dict.cc]:
[source,bash]
----
#!/bin/bash
echo "open -t http://www.dict.cc/?s=$QUTE_SELECTED_TEXT" >> "$QUTE_FIFO"
----

View File

@ -71,6 +71,7 @@ def main(colors=False):
asciidoc_files = [
('doc/FAQ.asciidoc', 'qutebrowser/html/doc/FAQ.html'),
('doc/quickstart.asciidoc', 'qutebrowser/html/doc/quickstart.html'),
('doc/userscripts.asciidoc', 'qutebrowser/html/doc/userscripts.html'),
]
try:
os.mkdir('qutebrowser/html/doc')