README.md - plumber - Plumber – a modern approach to plumbing
(HTM) git clone git://r-36.net/plumber
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
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