README.md (6113B)
1 # Plumber – a modern approach 2 3 ## Introduction 4 5 Plumber is like xdg-open(1) but much more powerful. For now it's my personal 6 toy to help me handle all kind of URIs and speed up my daily life. 7 8 ## License 9 10 See the LICENSE file for the terms. 11 12 ## Dependencies 13 * Python 14 * mailcap(1), for local file handling 15 * no need for duplication 16 * There are dependencies in the openers. See the openers for their 17 dependencies. 18 19 ## Installation 20 21 Installation of plumb can be done manually or via the makefile. By 22 default it installs to `bin` inside the user's home directory (note: 23 some plumb users find it is easiest to install plumb to 24 `/usr/local/bin`.) After plumb is installed, you should probably add 25 the program's location to the user's path and export environmental 26 variables for openers. 27 28 % export PATH="$PATH:<location_of_plumb>" 29 % export XTERM=<your preferred_xterminal xterm?> 30 % export PLUMB_IMAGE=<your_preferred_image_viewer feh -F --auto-rotate?> 31 % export PLUMB_MEDIA=<your_preferred_mediaplayer mpv?> 32 % export PLUMB_GOPHER=<your_preferred_gopher_browser gopher?> 33 % export PLUMB_TXTGOPHER=<your_preferred_gopher_textbrowser gopher?> 34 % export PLUMB_PDF=<your_preferred_pdf_viewer xpdf?> 35 % export PLUMB_FILEMANAGER=<your_preferred_filemanager ranger?> 36 % export PLUMB_WEB=<your_preferred_webbrowser firefox?> 37 % export PLUMB_TXTWEB=<your_preferred_text_webbrowser lynx?> 38 % export PLUMB_FEED=<your_preferred_RSS/Atom_client thunderbird?> 39 % export PLUMB_WAIS=<your_preferred_WAIS_client lynx?> 40 % export PLUMB_CSO=<your_preferred_CSO_client lynx?> 41 % export PLUMB_NEWS=<your_preferred_NNTP/NEWS_client lynx?> 42 % export PLUMB_NEX=<your_preferred_NEX_client ?> 43 44 ### Manual 45 46 # Copy the symlinks you like. I use all of them. 47 % cp bin/plumber $HOME/bin 48 % cp -a bin/p $HOME/bin 49 % cp -a bin/plumb $HOME/bin 50 % cp -a bin/Þ $HOME/bin 51 % cp openers/* $HOME/bin 52 # Required for dwm integration: 53 % cp bin/opener $HOME/bin 54 % export XTERM=<your_preferred_xterminal> 55 # Add the above to your .mkshrc or .bashrc to make permanent. 56 57 ### Makefile 58 59 # Install plumb to user's $HOME 60 % make install 61 # Or, install to a specific directory 62 % make install DESTDIR=/usr/local/bin 63 64 ## Usage 65 66 % p http://www.searx.me 67 % echo "http://searx.me" | p 68 % echo -e "http://searx.me\nhttp://google.com\n" | p -me 69 % echo "Please go to http://searx.me please." | p -tme 70 # Be surprised about the ease of usage! 71 72 ### st (simple terminal) integration 73 74 In my setup I am calling »plumber -tme« via the externalpipe patch, applied to 75 st mainline. The config.h would include: 76 77 { MODKEY, XK_o, externalpipe, {.v = "plumber -tme" } }, 78 79 ### dwm (dynamic window manager) integration 80 81 For using the plumber in dwm I have the »opener(1)« script, which gets the 82 X11 selection and gives it to the plumber. Here is the config.h entry: 83 84 { MODKEY, XK_o, spawn, SHCMD("opener") }, 85 86 This allows something really valuable: Select some text and press Mod + o, 87 which opens the selected text. If you use double click to select some URI or 88 text, plumber has included stripping support to shorten quotation marks or 89 (square) brackets. 90 91 ### urxvt 92 93 Urxvt integrates with plumber beautifully because of urxvt-matcher. 94 urxvt-matcher can highlight strings of interest like URLs and pass these 95 along to plumber, where they will be opened with the assigned opener. To 96 do this, you will need to have urxvt-matcher installed on your system. 97 Then add the following line to your .Xresources: 98 99 URxvt.matcher.launcher: plumb $0 100 URxvt.matcher.button: 1 101 102 Additional URLs can be matched and launched by specifying more patterns 103 to urxvt-matcher, as below where two patterns are added for launching 104 gopher and gophers: 105 106 URxvt.matcher.pattern.1: \\b(gopher\\:\\/\\/\\S+)\\b 107 URxvt.matcher.launcher.1: plumb $1 108 URxvt.matcher.pattern.2: \\b(gophers\\:\\/\\/\\S+)\\b 109 URxvt.matcher.launcher.2: plumb $1 110 111 To see and select the matches, you press M-Del on your keyboard to invoke 112 match-select. Then use the up and down arrows to move between matches. 113 Press enter to send a selected match to plumb. 114 115 ## Openers 116 117 The distribution includes nearly all openers I have written for my local use 118 case. You will find many local constructs, to show you the possibilities of 119 the plumber(1) architecture. To keep plumber as flexible as possible I did not 120 introduce any intermediate description language or yet another scripting 121 language. It is all calling scripts and calling scripts all the way down. 122 123 For adding some opener, just create the script (I name them \*opener.) and 124 reference them from plumber(1). 125 126 Many helper applications are not included. You will find them in further 127 published applications in my git repository. If you feel interest in some, 128 contact me and I am open to give away the source code. 129 130 ## How does it work? 131 132 There is a hierarchy of URIs. First of all the scheme is parsed, like 133 »http://« or »portage:«, then some opener is called. If the URI or string 134 given to the plumber is a local file, »see« (part of mailcap) is run, which 135 will do the mime parsing and is configured through your $HOME/.mailcap. See 136 the appropriate manpages, how to configure this. 137 138 When the plumber calls a helper, there are simple and complex openers. For a 139 really complex one, see the webopener(1). It allows for now just one fun 140 parsing for the headers, just for the demonstration of what's possible. You 141 could do all kind of cache checking or header parsing before calling some 142 application. 143 144 If you see my example plumber(1) script, you notice that you need to edit the 145 python file. That's way easier than having to parse a file on every startup. 146 Making this a configuration file would be easy but out of scope. In the end 147 you write your own handlers, which includes coding. Without coding plumber(1) 148 will not help you much. 149 150 Back to the web example. As you see, images are handled directly, instead of 151 going through a huge bloated webbrowser. Text files are given to a text web 152 browser and so stop you from seeing all the web bloat and time wasting 153 advertisements. 154 155 ## Changes, Bugs, Patches 156 157 Please send them to: 158 159 Christoph Lohmann <20h@r-36.net> 160 161 Have fun! 162