README.md (6063B)
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 43 ### Manual 44 45 # Copy the symlinks you like. I use all of them. 46 % cp bin/plumber $HOME/bin 47 % cp -a bin/p $HOME/bin 48 % cp -a bin/plumb $HOME/bin 49 % cp -a bin/Þ $HOME/bin 50 % cp openers/* $HOME/bin 51 # Required for dwm integration: 52 % cp bin/opener $HOME/bin 53 % export XTERM=<your_preferred_xterminal> 54 # Add the above to your .mkshrc or .bashrc to make permanent. 55 56 ### Makefile 57 58 # Install plumb to user's $HOME 59 % make install 60 # Or, install to a specific directory 61 % make install DESTDIR=/usr/local/bin 62 63 ## Usage 64 65 % p http://www.searx.me 66 % echo "http://searx.me" | p 67 % echo -e "http://searx.me\nhttp://google.com\n" | p -me 68 % echo "Please go to http://searx.me please." | p -tme 69 # Be surprised about the ease of usage! 70 71 ### st (simple terminal) integration 72 73 In my setup I am calling »plumber -tme« via the externalpipe patch, applied to 74 st mainline. The config.h would include: 75 76 { MODKEY, XK_o, externalpipe, {.v = "plumber -tme" } }, 77 78 ### dwm (dynamic window manager) integration 79 80 For using the plumber in dwm I have the »opener(1)« script, which gets the 81 X11 selection and gives it to the plumber. Here is the config.h entry: 82 83 { MODKEY, XK_o, spawn, SHCMD("opener") }, 84 85 This allows something really valuable: Select some text and press Mod + o, 86 which opens the selected text. If you use double click to select some URI or 87 text, plumber has included stripping support to shorten quotation marks or 88 (square) brackets. 89 90 ### urxvt 91 92 Urxvt integrates with plumber beautifully because of urxvt-matcher. 93 urxvt-matcher can highlight strings of interest like URLs and pass these 94 along to plumber, where they will be opened with the assigned opener. To 95 do this, you will need to have urxvt-matcher installed on your system. 96 Then add the following line to your .Xresources: 97 98 URxvt.matcher.launcher: plumb $0 99 URxvt.matcher.button: 1 100 101 Additional URLs can be matched and launched by specifying more patterns 102 to urxvt-matcher, as below where two patterns are added for launching 103 gopher and gophers: 104 105 URxvt.matcher.pattern.1: \\b(gopher\\:\\/\\/\\S+)\\b 106 URxvt.matcher.launcher.1: plumb $1 107 URxvt.matcher.pattern.2: \\b(gophers\\:\\/\\/\\S+)\\b 108 URxvt.matcher.launcher.2: plumb $1 109 110 To see and select the matches, you press M-Del on your keyboard to invoke 111 match-select. Then use the up and down arrows to move between matches. 112 Press enter to send a selected match to plumb. 113 114 ## Openers 115 116 The distribution includes nearly all openers I have written for my local use 117 case. You will find many local constructs, to show you the possibilities of 118 the plumber(1) architecture. To keep plumber as flexible as possible I did not 119 introduce any intermediate description language or yet another scripting 120 language. It is all calling scripts and calling scripts all the way down. 121 122 For adding some opener, just create the script (I name them \*opener.) and 123 reference them from plumber(1). 124 125 Many helper applications are not included. You will find them in further 126 published applications in my git repository. If you feel interest in some, 127 contact me and I am open to give away the source code. 128 129 ## How does it work? 130 131 There is a hierarchy of URIs. First of all the scheme is parsed, like 132 »http://« or »portage:«, then some opener is called. If the URI or string 133 given to the plumber is a local file, »see« (part of mailcap) is run, which 134 will do the mime parsing and is configured through your $HOME/.mailcap. See 135 the appropriate manpages, how to configure this. 136 137 When the plumber calls a helper, there are simple and complex openers. For a 138 really complex one, see the webopener(1). It allows for now just one fun 139 parsing for the headers, just for the demonstration of what's possible. You 140 could do all kind of cache checking or header parsing before calling some 141 application. 142 143 If you see my example plumber(1) script, you notice that you need to edit the 144 python file. That's way easier than having to parse a file on every startup. 145 Making this a configuration file would be easy but out of scope. In the end 146 you write your own handlers, which includes coding. Without coding plumber(1) 147 will not help you much. 148 149 Back to the web example. As you see, images are handled directly, instead of 150 going through a huge bloated webbrowser. Text files are given to a text web 151 browser and so stop you from seeing all the web bloat and time wasting 152 advertisements. 153 154 ## Changes, Bugs, Patches 155 156 Please send them to: 157 158 Christoph Lohmann <20h@r-36.net> 159 160 Have fun! 161