plumber

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

README.md (3778B)


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