plumber

Plumber – a modern approach to plumbing
git clone git://r-36.net/plumber
Log | Files | Refs | LICENSE

README.md (3666B)


      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 	# Copy the symlinks you like. I use all of them.
     22 	% cp bin/plumber $HOME/bin
     23 	% cp -a bin/p $HOME/bin
     24 	% cp -a bin/plumb $HOME/bin
     25 	% cp -a bin/Þ $HOME/bin
     26 	% cp openers/* $HOME/bin
     27 	# Required for dwm integration:
     28 	% cp bin/opener $HOME/bin
     29 
     30 ## Usage
     31 
     32 	% p http://www.searx.me
     33 	% echo "http://searx.me" | p
     34 	% echo -e "http://searx.me\nhttp://google.com\n" | p -me
     35 	% echo "Please go to http://searx.me please." | p -tme
     36 	# Be surprised about the ease of usage!
     37 
     38 ## st (simple terminal) integration
     39 
     40 In my setup I am calling »plumber -tme« via the externalpipe patch, applied to
     41 st mainline. The config.h would include:
     42 
     43 	{ MODKEY, XK_o, externalpipe, {.v = "plumber -tme" } },
     44 
     45 ## dwm (dynamic window manager) integration
     46 
     47 For using the plumber in dwm I have the »opener(1)« script, which gets the
     48 X11 selection and gives it to the plumber. Here is the config.h entry:
     49 
     50 	{ MODKEY, XK_o, spawn, SHCMD("opener") },
     51 
     52 This allows something really valuable: Select some text and press Mod + o,
     53 which opens the selected text. If you use double click to select some URI or
     54 text, plumber has included stripping support to shorten quotation marks or
     55 (square) brackets.
     56 
     57 ## Openers
     58 
     59 The distribution includes nearly all openers I have written for my local use
     60 case. You will find many local constructs, to show you the possibilities of
     61 the plumber(1) architecture. To keep plumber as flexible as possible I did not
     62 introduce any intermediate description language or yet another scripting
     63 language. It is all calling scripts and calling scripts all the way down.
     64 
     65 For adding some opener, just create the script (I name them \*opener.) and
     66 reference them from plumber(1).
     67 
     68 Many helper applications are not included. You will find them in further
     69 published applications in my git repository. If you feel interest in some,
     70 contact me and I am open to give away the source code.
     71 
     72 ## How does it work?
     73 
     74 There is a hierarchy of URIs. First of all the scheme is parsed, like
     75 »http://« or »portage:«, then some opener is called. If the URI or string
     76 given to the plumber is a local file, »see« (part of mailcap) is run, which
     77 will do the mime parsing and is configured through your $HOME/.mailcap. See
     78 the appropriate manpages, how to configure this.
     79 
     80 When the plumber calls a helper, there are simple and complex openers. For a
     81 really complex one, see the webopener(1). It allows for now just one fun
     82 parsing for the headers, just for the demonstration of what's possible. You
     83 could do all kind of cache checking or header parsing before calling some
     84 application.
     85 
     86 If you see my example plumber(1) script, you notice that you need to edit the
     87 python file. That's way easier than having to parse a file on every startup.
     88 Making this a configuration file would be easy but out of scope. In the end
     89 you write your own handlers, which includes coding. Without coding plumber(1)
     90 will not help you much.
     91 
     92 Back to the web example. As you see, images are handled directly, instead of
     93 going through a huge bloated webbrowser. Text files are given to a text web
     94 browser and so stop you from seeing all the web bloat and time wasting
     95 advertisements.
     96 
     97 ## Changes, Bugs, Patches
     98 
     99 Please send them to:
    100 
    101 	Christoph Lohmann <20h@r-36.net>
    102 
    103 Have fun!
    104