Debian Codegraph @

doc/apparix.html

raw ◀ ▶
1 Debian patch touch this file
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <html>
3 <!-- Copyright (c) 2011 Stijn van Dongen -->
4 <head>
5 <meta name="keywords" content="manual">
6 <style type="text/css">
7 /* START aephea.base.css */
8 body
9 { text-align: justify;
10 margin-left: 0%;
11 margin-right: 0%;
12 }
13 a:link { text-decoration: none; }
14 a:active { text-decoration: none; }
15 a:visited { text-decoration: none; }
16 a:link { color: #1111aa; }
17 a:active { color: #1111aa; }
18 a:visited { color: #111166; }
19 a.local:link { color: #11aa11; }
20 a.local:active { color: #11aa11; }
21 a.local:visited { color: #116611; }
22 a.intern:link { color: #1111aa; }
23 a.intern:active { color: #1111aa; }
24 a.intern:visited { color: #111166; }
25 a.extern:link { color: #aa1111; }
26 a.extern:active { color: #aa1111; }
27 a.extern:visited { color: #661111; }
28 a.quiet:link { color: black; }
29 a.quiet:active { color: black; }
30 a.quiet:visited { color: black; }
31 div.verbatim
32 { font-family: monospace;
33 margin-top: 1em;
34 margin-bottom: 1em;
35 font-size: 10pt;
36 margin-left: 2em;
37 white-space: pre;
38 }
39 div.indent
40 { margin-left: 8%;
41 margin-right: 0%;
42 }
43 .right { text-align: right; }
44 .left { text-align: left; }
45 .nowrap { white-space: nowrap; }
46 .item_leader
47 { position: relative;
48 margin-left: 8%;
49 }
50 .item_compact { position: absolute; vertical-align: baseline; }
51 .item_cascade { position: relative; }
52 .item_leftalign { text-align: left; }
53 .item_rightalign
54 { width: 2em;
55 text-align: right;
56 }
57 .item_compact .item_rightalign
58 { position: absolute;
59 width: 52em;
60 right: -2em;
61 text-align: right;
62 }
63 .item_text
64 { position: relative;
65 margin-left: 3em;
66 }
67 .smallcaps { font-size: smaller; text-transform: uppercase }
68 acronym.ucase { font-size: smaller; text-transform: uppercase }
69 abbr.ucase { font-size: smaller; text-transform: uppercase }
70 /* END aephea.base.css */
71 body { font-family: "Garamond", "Gill Sans", "Verdana", sans-serif; }
72 body
73 { text-align: justify;
74 margin-left: 8%;
75 margin-right: 8%;
76 }
77 </style>
78 <title>apparix, augmenting the shell with directory bookmarks</title>
79 </head>
80 <body>
81 <p style="text-align:right">
82 3 Mar 2011&nbsp;&nbsp;&nbsp;
83 <a class="local" href="apparix.ps"><b>apparix</b></a>
84 1.004, 11-062
85 </p>
86 <div class=" itemize " style="margin-top:1em; font-size:100%">
87 <div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">1.</div></div>
88 <div class=" item_text " style="margin-left:4em">
89 <a class="intern" href="#name">NAME</a>
90 </div>
91 <div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">2.</div></div>
92 <div class=" item_text " style="margin-left:4em">
93 <a class="intern" href="#synopsis">SYNOPSIS</a>
94 </div>
95 <div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">3.</div></div>
96 <div class=" item_text " style="margin-left:4em">
97 <a class="intern" href="#gs">GETTING STARTED</a>
98 </div>
99 <div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">4.</div></div>
100 <div class=" item_text " style="margin-left:4em">
101 <a class="intern" href="#description">DESCRIPTION</a>
102 </div>
103 <div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">5.</div></div>
104 <div class=" item_text " style="margin-left:4em">
105 <a class="intern" href="#dup">duplicate resolution</a>
106 </div>
107 <div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">6.</div></div>
108 <div class=" item_text " style="margin-left:4em">
109 <a class="intern" href="#sub">subdirectory specification</a>
110 </div>
111 <div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">7.</div></div>
112 <div class=" item_text " style="margin-left:4em">
113 <a class="intern" href="#tab">tab completion</a>
114 </div>
115 <div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">8.</div></div>
116 <div class=" item_text " style="margin-left:4em">
117 <a class="intern" href="#edit">editing bookmarks</a>
118 </div>
119 <div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">9.</div></div>
120 <div class=" item_text " style="margin-left:4em">
121 <a class="intern" href="#mov">copying and moving files</a>
122 </div>
123 <div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">10.</div></div>
124 <div class=" item_text " style="margin-left:4em">
125 <a class="intern" href="#list">listing bookmarks</a>
126 </div>
127 <div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">11.</div></div>
128 <div class=" item_text " style="margin-left:4em">
129 <a class="intern" href="#cd">replacing cd</a>
130 </div>
131 <div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">12.</div></div>
132 <div class=" item_text " style="margin-left:4em">
133 <a class="intern" href="#options">OPTIONS</a>
134 </div>
135 <div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">13.</div></div>
136 <div class=" item_text " style="margin-left:4em">
137 <a class="intern" href="#environment">ENVIRONMENT</a>
138 </div>
139 <div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">14.</div></div>
140 <div class=" item_text " style="margin-left:4em">
141 <a class="intern" href="#files">FILES</a>
142 </div>
143 <div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">15.</div></div>
144 <div class=" item_text " style="margin-left:4em">
145 <a class="intern" href="#notes">NOTES</a>
146 </div>
147 <div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">16.</div></div>
148 <div class=" item_text " style="margin-left:4em">
149 <a class="intern" href="#bugs">BUGS</a>
150 </div>
151 <div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">17.</div></div>
152 <div class=" item_text " style="margin-left:4em">
153 <a class="intern" href="#author">AUTHOR</a>
154 </div>
155 <div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">18.</div></div>
156 <div class=" item_text " style="margin-left:4em">
157 <a class="intern" href="#thanks">THANKS</a>
158 </div>
159 <div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">19.</div></div>
160 <div class=" item_text " style="margin-left:4em">
161 <a class="intern" href="#history">HISTORY</a>
162 </div>
163 </div>
164
165 <a name="name"></a>
166 <h2>NAME</h2>
167 <p style="margin-bottom:0" class="asd_par">
168 apparix &mdash; augmenting cd with bookmarks</p>
169
170 <a name="synopsis"></a>
171 <h2>SYNOPSIS</h2>
172 <p style="margin-bottom:0" class="asd_par">
173 Apparix allows you to bookmark directories and later jump to them using the mark.
174 By default apparix acts as a replacement for <i>cd</i> and can be used in the
175 same manner, including the special behaviour for <i>cd</i> without argument
176 and <i>cd</i>&nbsp;<tt>-</tt>.
177 It is possible to directly jump to subdirectories of a bookmarked directory.
178 The contributed bash completion code facilitates completion both on
•179 bookmarks and directories, but can be adjusted to accommodate other
180 preferences.
181 </p>
182 <p style="margin-bottom:0" class="asd_par">
183 This manual page suffers from an excess in verbosity due to the many
184 examples, explanations of the bells and whistles, and comparisons with other
185 approaches to bookmarking. The fundamental idea is simply that typing a
186 string of your own choosing takes you to the directory associated with it.
187 Apparix does little more than maintaining a list of keys and values.
188 It obtains directory names and listings, associates
189 path names (values) with bookmarks (keys), and has some facilities for
190 manipulating keys and values. The functions involving apparix
191 (<b>bm</b>, <b>to</b>, and <b>portal</b>) provide the user interface.
192 Other functions, <b>als</b> (apparix ls) and <b>ae</b> (apparix edit)
193 are discussed on the main apparix page <a class="extern" target="_parent" href="http://micans.org/apparix">http://micans.org/apparix</a>.
194 </p>
195
196 <a name="gs"></a>
197 <h2>GETTING STARTED</h2>
198 <p style="margin-bottom:0" class="asd_par">
199 Install apparix. This should be as easy as <tt>./configure --prefix=$HOME/local &amp;&amp; make &amp;&amp; make install</tt>,
200 or perhaps a pre-packaged apparix is available for your system.
201 Then get hold of the <b>to</b>, <b>bm</b> and <b>portal</b> shell handles. These
202 are either aliases or functions depending on your shell. Currently csh-style
203 shells and bash are supported.
204 Get the ones you need preferably from
205 <a class="extern" target="_parent" href="http://micans.org/apparix/#shell">http://micans.org/apparix/#shell</a>. For a more limited set of
206 commands either visit the <a class="intern" href="#files">FILES</a> section, or issue <tt>apparix
207 --shell-examples</tt>. Activate them by simply pasting them in a shell or adding
208 them to the appropriate resource file, e.g. <tt>$HOME/.cshrc</tt> or
209 <tt>$HOME/.bashrc</tt> (do not forget to <i>source</i> the resource file). The
210 handles <b>to</b>, <b>bm</b> and <b>portal</b> can of course be changed to any
211 name desired. With these preliminaries, the following is a mock-up shell
212 navigation session.
213 </p>
214 <div class="verbatim"> &gt; <b>pwd</b>
215 /home/eez/cvs/xyz/tfa/faq/zut/bar/foo
216 &gt; <b>ls</b>
217 src/ doc/ CVS/ bin/
218 &gt; <b>bm xkr</b> # bookmark as xkr (funny name though)
219 &gt; <b>bm</b> # bookmark as foo (trailing component is default)
220 (later)
221 &gt; <b>to xkr</b> # cd to /home/eez/cvs/xyz/tfa/faq/zut/bar/foo
222 (alternatively)
223 &gt; <b>to xkr src</b> # cd to /home/eez/cvs/xyz/tfa/faq/zut/bar/foo/src
224 (alternatively)
225 &gt; <b>to foo</b> # cd to /home/eez/cvs/xyz/tfa/faq/zut/bar/foo
226
227 (later)
228 &gt; <b>ls</b>
229 aap pyu/ qua tim/ zut/
230 &gt; <b>pwd</b>
231 /home/eez/another/branch/deep/down/under
232 &gt; <b>portal</b> # bookmark as portal, imports tim zut pyu bookmarks
233 added flock of 3 in portal /home/eez/another/branch/deep/down/under
234
235 (later)
236 &gt; <b>to zut</b> # cd to /home/eez/another/branch/deep/down/under/zut
237
238 (later)
239 &gt; <b>apparix</b> # show all bookmarks
240 --- portals
241 e /home/eez/another/branch/deep/down/under
242 --- expansions
243 j pyu /home/eez/another/branch/deep/down/under/pyu
244 j tim /home/eez/another/branch/deep/down/under/tim
245 j zut /home/eez/another/branch/deep/down/under/zut
246 --- bookmarks
247 j xkr /home/eez/cvs/xyz/tfa/faq/zut/bar/foo
248 j foo /home/eez/cvs/xyz/tfa/faq/zut/bar/foo</div>
249 <p style="margin-top:0em; margin-bottom:0em">
250 In the last example apparix simply shows all its bookmarks. The first batch
251 shows portals. The second batch shows secondary bookmarks expanded from
252 portals. The third batch shows all regular bookmarks.
253 </p>
254 <p style="margin-bottom:0" class="asd_par">
255 In the default definitions of <b>to</b> it falls back to regular <i>cd</i>
256 behaviour in case a mark is not found. This is done by instructing apparix
257 to check whether the mark exists as the name of a directory. It is possible
258 to do this either before or after bookmark lookup, or not at all. By default
259 the bash completion code takes into account both bookmarks and directories.
260 </p>
261 <p style="margin-bottom:0" class="asd_par">
262 Apparix also allows subdirectory specification of bookmarked locations. If
263 this is combined with the bash completion code it yields a powerful way of
264 navigating container directories, i.e. directories that contain a large
265 number of subdirectories. Refer to the <a class="intern" href="#sub">subdirectory specification</a> section.
266 </p>
267 <p style="margin-bottom:0"><b>Further options</b><br>
268 <a class="intern" href="#opt--add-mark"><b>[--add-mark</b> (<i>add jump bookmark</i>)<b>]</b></a>
269 <a class="intern" href="#opt--add-portal"><b>[--add-portal</b> (<i>add portal bookmark</i>)<b>]</b></a>
270 <a class="intern" href="#opt-sm"><b>[-sm</b> &lt;mark&gt; (<i>squash repeated marks</i>)<b>]</b></a>
271 <a class="intern" href="#opt-sd"><b>[-sd</b> &lt;mark&gt; (<i>squash repeated destinations</i>)<b>]</b></a>
272 <a class="intern" href="#opt-lm"><b>[-lm</b> &lt;mark&gt; (<i>list bookmarks with this mark</i>)<b>]</b></a>
273 <a class="intern" href="#opt-ld"><b>[-ld</b> &lt;mark&gt; (<i>list destinations with mark indirection</i>)<b>]</b></a>
274 <a class="intern" href="#opt-favour"><b>[-favour</b> &lt;list&gt; (<i>duplicate resolution policy</i>)<b>]</b></a>
275 <a class="intern" href="#opt-pick"><b>[-pick</b> &lt;num&gt; (<i>immediate duplicate resolution</i>)<b>]</b></a>
276 <a class="intern" href="#opt-purge"><b>[-purge</b> pat (<i>delete bookmarks</i>)<b>]</b></a>
277 <a class="intern" href="#opt-purge-mark"><b>[-purge-mark</b> (<i>pat</i>)<b>]</b></a>
278 <a class="intern" href="#opt-d"><b>[-d</b> (<i>dump resource file to STDOUT</i>)<b>]</b></a>
279 <a class="intern" href="#opt-l"><b>[-l</b> (<i>list available jumps</i>)<b>]</b></a>
280 <a class="intern" href="#opt-u"><b>[-u</b> &lt;num&gt; (<i>remove last &lt;num&gt; additions</i>)<b>]</b></a>
281 <a class="intern" href="#opt--rehash"><b>[--rehash</b> (<i>re-expand portal bookmarks</i>)<b>]</b></a>
282 <a class="intern" href="#opt--bu"><b>[--bu</b> (<i>create backup of resource file</i>)<b>]</b></a>
283 <a class="intern" href="#opt-bu"><b>[-bu</b> &lt;fname&gt; (<i>create backup in &lt;fname&gt;</i>)<b>]</b></a>
284 <a class="intern" href="#opt--cwd"><b>[--cwd</b> (<i>use getcwd(3), not pwd(1)</i>)<b>]</b></a>
285 <a class="intern" href="#opt--shell-examples"><b>[--shell-examples</b> (<i>output example macros</i>)<b>]</b></a>
286 </p>
287
288 <a name="description"></a>
289 <h2>DESCRIPTION</h2>
290 <p style="margin-bottom:0" class="asd_par">
291 Apparix combines the properties of the
292 <a target="_parent" class="extern" href="http://www.skamphausen.de/cgi-bin/ska/CDargs">cdargs</a> utility and the
293 CDPATH shell mechanism for fast navigation through the file system. It can
294 additionally act as the regular <i>cd</i> command. It is especially useful for
295 visiting and documenting both often- and rarely-used locations. Apparix
296 enables you to attach marks to locations and jump to those locations by
297 loading the mark. Marking, unmarking and jumping are simple operations that
298 are performed in the shell. All actions take effect immediately in all
299 shells running. By setting up convenient aliases for marking and jumping
300 the file system can be navigated in a fast and intuitive manner. The
301 <a class="intern" href="#files">FILES</a> section lists aliases for csh-type shells and functions for
302 bash, including the setup to equip the <b>to</b> function with argument
303 completion in bash.
304 </p>
305 <p style="margin-bottom:0" class="asd_par">
306 This section contains some examples of the most common uses
307 of apparix.
308 <a class="intern" href="#options">OPTIONS</a> contains a list of additional options available
309 for listing, pruning, and squashing bookmarks.</p>
310 <p style="margin-bottom:0" class="asd_par">
311 <a class="intern" href="#notes">NOTES</a> features a brief discussion of the advantages
312 of apparix over other approaches such as setting up aliases for
313 often visited directories, using symlinks, CDPATH, or a combination
314 of these. <a class="intern" href="#history">HISTORY</a> explains the difference between
315 cdargs and apparix.
316 The sections <a class="intern" href="#dup">duplicate resolution</a>, <a class="intern" href="#sub">subdirectory specification</a>, <a class="intern" href="#tab">tab completion</a>,
317 <a class="intern" href="#mov">copying and moving files</a>, <a class="intern" href="#list">listing bookmarks</a>, and <a class="intern" href="#cd">replacing cd</a>
318 further below are also recommended reading.</p>
319 <p style="margin-bottom:0" class="asd_par">
320 Apparix works in a manner similar to cdargs. One usually invokes
321 apparix by using pre-defined aliases. Here they will be called <b>bm</b> for
322 bookmark, <b>portal</b> for a CDPATH-style bookmark and <b>to</b> for initiating
323 an apparition (aka jump).
324 These aliases are found below in the <a class="intern" href="#files">FILES</a>
325 section and can also be obtained by issuing</p>
326 <div class="verbatim">apparix --shell-examples</div>
327 <p style="margin-bottom:0" class="asd_par">
328 Suppose your user name is <i>eez</i> and your home directory is <tt>/home/eez</tt>.
329 You often visit a directory called
330 <tt>/home/eez/cvs/xyz/tfa/faq/zut/bar/foo</tt>.
331 This is how to create and use a bookmark for foo</p>
332 <div class="verbatim">/home/eez/cvs/xyz/tfa/faq/zut/bar/foo&gt; <b>bm foo</b>
333 added: foo -&gt; /home/eez/cvs/xyz/tfa/faq/zut/bar/foo
334 /home/eez/cvs/xyz/tfa/faq/zut/bar/foo&gt; <b>cd</b>
335 /home/eez&gt; <b>to foo</b>
336 /home/eez/cvs/xyz/tfa/faq/zut/bar/foo&gt;</div>
337 <p style="margin-top:0em; margin-bottom:0em">
338 If one bookmarks a directory by its trailing component as happened in
339 this case, it is not necessary to specify the mark. By default apparix
340 will use the trailing component as the mark. So</p>
341 <div class="verbatim">/home/eez/cvs/xyz/tfa/faq/zut/bar/foo&gt; <b>bm</b>
342 added: foo -&gt; /home/eez/cvs/xyz/tfa/faq/zut/bar/foo</div>
343 <p style="margin-top:0em; margin-bottom:0em">gives the same result.</p>
344 <p style="margin-bottom:0" class="asd_par">
345 Another scenario is where you have some directory that contains a largish
346 number of subdirectories, all of which you would like to have bookmarked.
347 If the subdirectories have distinctive names this can be achieved in
348 one fell swoop by marking the parent directory as a <i>portal</i>. This is
349 similar to adding the parent directory to the CDPATH environment variable,
350 except that apparix bookmarks are not part of the cd namespace. It is
351 argued in <a class="intern" href="#notes">NOTES</a> that this is a good thing.
352 Consider this:</p>
353 <div class="verbatim">/home/cvs/bagger/boemel/mcl/mcl/src&gt; <b>ls</b>
354 alien/ CVS/ impala/ Makefile.am README shmcx/
355 attic/ giraffe/ lib/ Makefile.in shcl/ shmx/
356 contrib/ gmon.out Makefile mcl/ shmcl/ taurus/</div>
357 <p style="margin-top:0em; margin-bottom:0em">
358 Some of the subdirectories have not-so-distinct names such as <i>contrib</i> and
359 <i>attic</i>, but they happen to be the directories least visited.
360 Issuing:</p>
361 <div class="verbatim">/home/cvs/bagger/boemel/mcl/mcl/src&gt; <b>portal</b>
362 [apparix] expanded 1 portal to 12 destinations</div>
363 <p style="margin-top:0em; margin-bottom:0em">
364 yields all of the subdirectories as destinations bookmarked by the last
365 component of their path name.
366 Incidentally, directory names such as <tt>CVS</tt> can be explicitly excluded
367 from expansion by setting the environment variable <tt>APPARIXEXCLUDE</tt>
368 appropriately &mdash; refer to section <a class="intern" href="#environment">ENVIRONMENT</a>.
369 </p>
370 <p style="margin-bottom:0" class="asd_par">
371 Bookmarks resulting from portal expansion are kept in a separate
372 resource file (see <a class="intern" href="#files">FILES</a>). Portal expansions can be recreated
373 by issuing</p>
374 <div class="verbatim">apparix --rehash</div>
375 <p style="margin-top:0em; margin-bottom:0em">
376 This is useful to reflect a change in the directory naming structure
377 underneath a portal.</p>
378
379 <a name="dup"></a>
380 <h2>duplicate resolution</h2>
381 <p style="margin-bottom:0" class="asd_par">
382 Apparix allows identical bookmarks to point to different locations.
383 When asked to visit such a bookmark it will by default
384 present a list of options.</p>
385 <p style="margin-bottom:0" class="asd_par">
386 The <a class="intern" href="#opt-favour"><b>-favour</b>&nbsp;<i>&lt;list&gt;</i></a> option can be used to automate
387 resolution. <b>&lt;list&gt;</b> is a sequence of single characters,
388 described further below.
389 The order in which they are given denote the order in which
390 resolution rules are applied. This option is typically used
391 in the definition of the <b>to</b> function/alias or
392 in the bash completion code.</p>
393 <p style="margin-bottom:0" class="asd_par">
394 The <a class="intern" href="#opt-pick"><b>-pick</b>&nbsp;<i>&lt;num&gt;</i></a> option is used to resolve to a particular
395 directory directly. This is useful when you already know where you want to
396 go, and typically used for the <tt>now</tt> bookmark in conjunction with the bash
397 <tt>whence</tt> function. Use <tt>whence now</tt> to see an indexed list of now
398 bookmarks. It is possible to go to the desired directory by entering the
399 bookmark index. It is possible to bypass the selection step by specifying
400 <tt>whence now N</tt>.
401 </p>
402 <p style="margin-bottom:0" class="asd_par">
403 Duplicates are allowed because it can be useful to overwrite a bookmark with
404 a new location. The old bookmark is kept as a matter of policy. Use
405 <a class="intern" href="#opt-sm"><b>-sm</b></a> to explicitly squash duplicates.
406 </p>
407 <div class=" itemize " style="margin-top:1em; font-size:100%">
408 <div class=" item_compact"><div class=" item_leftalign nowrap " >l</div></div>
409 <div class=" item_text " style="margin-left:2em">
410 <p style="margin-top:0em; margin-bottom:0em">
411 <i>level</i>; prefer paths with fewer components.</p>
412 </div>
413 <div style="margin-top:0em">&nbsp;</div><div class=" item_compact"><div class=" item_leftalign nowrap " >L</div></div>
414 <div class=" item_text " style="margin-left:2em">
415 <p style="margin-top:0em; margin-bottom:0em">
416 reverse of the above.</p>
417 </div>
418 <div style="margin-top:0em">&nbsp;</div><div class=" item_compact"><div class=" item_leftalign nowrap " >o</div></div>
419 <div class=" item_text " style="margin-left:2em">
420 <p style="margin-top:0em; margin-bottom:0em">
421 <i>bookmark order</i>; prefer older entries.
422 Entries appearing earlier in the file are considered older,
423 but the actual date of creating the bookmark is not stored.
424 Refer to <a class="intern" href="#edit">editing bookmarks</a> for more information.</p>
425 </div>
426 <div style="margin-top:0em">&nbsp;</div><div class=" item_compact"><div class=" item_leftalign nowrap " >O</div></div>
427 <div class=" item_text " style="margin-left:2em">
428 <p style="margin-top:0em; margin-bottom:0em">
429 reverse of the above.</p>
430 </div>
431 <div style="margin-top:0em">&nbsp;</div><div class=" item_compact"><div class=" item_leftalign nowrap " >r</div></div>
432 <div class=" item_text " style="margin-left:2em">
433 <p style="margin-top:0em; margin-bottom:0em">
434 <i>regular first</i>; prefer regular bookmarks over portal expansion.</p>
435 </div>
436 <div style="margin-top:0em">&nbsp;</div><div class=" item_compact"><div class=" item_leftalign nowrap " >R</div></div>
437 <div class=" item_text " style="margin-left:2em">
438 <p style="margin-top:0em; margin-bottom:0em">
439 reverse of the above.</p>
440 </div>
441 </div>
442 <p style="margin-bottom:0" class="asd_par">
443 If there are still ties after the specified rules have
444 been applied apparix will simply take the first matching
445 option. This behaviour cannot be further specified
446 as the program uses a non-stable ordering routine.</p>
447 <p style="margin-bottom:0" class="asd_par">
448 It is an absolute prerequisite that <a class="intern" href="#opt-favour"><b>-favour</b></a> is used in the bash
449 completion code. Otherwise completion will fail (for a duplicated bookmark)
450 while apparix is waiting for input. Refer to the tab completion description
451 below.</p>
452
453 <a name="sub"></a>
454 <h2>subdirectory specification</h2>
455 <p style="margin-bottom:0" class="asd_par">
456 When jumping (apparating) you can specify an additional subdirectory
457 after the bookmark. Apparix will append the subdirectory to
458 the destination.</p>
459 <p style="margin-bottom:0" class="asd_par">
460 This is useful for projects with directory nodes corresponding
461 with versions. Assume you have a directory structure such as this:</p>
462 <div class="verbatim"> /x/y/z/OpusMagnum/v1/
463 /x/y/z/OpusMagnum/v2/
464 /x/y/z/OpusMagnum/v3/</div>
465 <p style="margin-bottom:0" class="asd_par">
466 It is probably easiest to simply bookmark the OpusMagnum directory
467 in some way (say with bookmark <tt>om</tt>). You can then issue
468 <tt>to om v2</tt> to jump to <tt>OpusMagnum/v2</tt>. This is more flexible
469 and maintainable than creating bookmarks <tt>om1</tt>, <tt>om2</tt>, <tt>om3</tt>.
470 One could add OpusMagnum as a portal, but with generic names such
471 as <tt>v1</tt> this is not a very extendible approach.</p>
472 <p style="margin-bottom:0" class="asd_par">
473 See also the tab completion description below - it is possible
474 to tab-complete on subdirectories of the apparix jump directory.</p>
475
476 <a name="tab"></a>
477 <h2>tab completion</h2>
478 <p style="margin-bottom:0" class="asd_par">
479 The bash tab completion code does two things. First, it is possible to
480 tab-complete on apparix bookmarks themselves, showing a listing of all
481 available bookmarks (or iterating through them in cyclic mode, depending on
482 your bash settings). Second, once a bookmark has been given tab completion
483 will list or iterate over all the subdirectories of the directory associated
484 with that bookmark. Specifying a string after the bookmark will limit
485 tab-completion to directories matching the shell-pattern in string.
486 <i>Very</i> useful.</p>
487 <p style="margin-bottom:0" class="asd_par">
488 Be careful to not remove the <a class="intern" href="#opt-favour"><b>-favour</b>&nbsp;<i>list</i></a> option
489 from the bash completion code. It is necessary to resolve
490 duplicate bookmarks.
491 </p>
492
493 <a name="edit"></a>
494 <h2>editing bookmarks</h2>
495 <p style="margin-top:0em; margin-bottom:0em">
496 Apparix appends new bookmarks to the end of the .apparixrc file. Nothing
497 stops you from editing the file, and this is in fact recommended if for
498 example you need to get rid of a bookmark and neither of <a class="intern" href="#opt-purge"><b>-purge</b></a>,
499 <a class="intern" href="#opt-purge-mark"><b>-purge-mark</b></a>, <a class="intern" href="#opt-sd"><b>-sd</b></a>,
500 <a class="intern" href="#opt-sm"><b>-sm</b></a> fulfills your needs. It was an easy design choice
501 not to equip apparix with editor capabilities.</p>
502
503 <a name="mov"></a>
504 <h2>copying and moving files</h2>
505 <p style="margin-bottom:0" class="asd_par">
506 It is straightforward to copy or move files to locations known
507 by apparix. Examples:</p>
508 <div class="verbatim">BASH and variants
509 cp FOO $(apparix zoem)
510 mv BAR $(apparix zoem doc)
511 mv BAR $(apparix zoem doc)/test
512
513 CSH and variants
514 cp FOO `apparix zoem`
515 mv BAR `apparix zoem doc`/test</div>
516
517 <a name="list"></a>
518 <h2>listing bookmarks</h2>
519 <p style="margin-bottom:0" class="asd_par">
520 Simply issuing apparix gives you a list of bookmarks grouped into three
521 categories, portals, expansions, and bookmarks. Use the <a class="intern" href="#opt-d"><b>-d</b></a> option
522 to dump the resource file to STDOUT exactly as it is. This can be useful
523 when you intend to use the <a class="intern" href="#opt-u"><b>-u</b>&nbsp;<i>num</i></a> option to remove bookmarks or
524 portals that were most recently added.</p>
525 <p style="margin-bottom:0" class="asd_par">
526 Use <a class="intern" href="#opt-l"><b>-l</b></a> to list all available jumps without their destinations.
527 The jumps are grouped into expansions resulting from portals and
528 regular bookmarks.</p>
529
530 <a name="cd"></a>
531 <h2>replacing cd</h2>
532 <p style="margin-bottom:0" class="asd_par">
533 With the supplied definition(s) of <b>to</b>, apparix will first see whether
534 the mark is the name of a directory, accessible from the current directory.
535 A directory is accessible if it would be a valid argument to cd, so it need
536 not necessarily be a subdirectory of the current directory. If the mark is
537 not an accessible directory, apparix will then try to do a lookup of the
538 mark in the bookmark files. This behaviour can be inverted to do the lookup
539 first and the current directory thereafter. Both modes can be used to make
540 <b>to</b> a drop-in replacement for <i>cd</i>. Additionally and again similar
541 to <i>cd</i>, <tt>'to -'</tt> will take you to the previous directory, and
542 specifying <tt>to</tt> without arguments will take you to your home directory.
543 </p>
544 <p style="margin-bottom:0" class="asd_par">
545 The bash completion code acts accordingly, and should transparently
546 complete on both marks and directories.
547 </p>
548
549 <a name="options"></a>
550 <h2>OPTIONS</h2>
551 <p style="margin-bottom:0" class="asd_par">
552 For bookmarking and jumping apparix is best invoked by using the aliases
553 (tcsh-variants) or functions (sh/bash) listed in <a class="intern" href="#files">FILES</a>.
554 Apparix has a few options that are useful for pruning, squashing and
555 rehasing bookmarks. These are best issued by invoking apparix directly.</p>
556 <p style="margin-bottom:0" class="asd_par">
557 If you are interested in marks or destinations matching a certain pattern,
558 simply issue apparix without arguments and pipe it through
559 your program of choice.</p>
560 <p style="margin-bottom:0" class="asd_par">
561 Unary options (those without arguments) usually start with two hyphens
562 except for standardized options such as <a class="intern" href="#opt-h"><b>-h</b></a>.
563 Options that take an argument can be converted to a unary key=value notation,
564 e.g. <b>-purge-mark</b>&nbsp;<b>foo</b> is equivalent to <b>--purge-mark</b>=<b>foo</b>.</p>
565 <p style="margin-bottom:0" class="asd_par">
566 When invoked without arguments apparix will simply dump its bookmarks.</p>
567 <div class=" itemize " style="margin-top:1em; font-size:100%">
568 <div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt--add-mark"></a><b>--add-mark</b> (<i>add jump bookmark</i>)</div></div>
569 <div class=" item_text " style="margin-left:2em">
570 <p style="margin-top:0em; margin-bottom:0em">
571 This options expects trailing <i>[mark [destination]]</i> argument(s).
572 Both arguments are optional. If a single argument is given it
573 is interpreted as a bookmark name to be mapped to the current directory.
574 If two arguments are given the last argument is taken as the
575 target directory. If no argument is given apparix will enlist
576 the current directory as a target bookmarked by the trailing component
577 of the directory path.</p>
578 </div>
579 <div style="margin-top:0em">&nbsp;</div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt--add-portal"></a><b>--add-portal</b> (<i>add portal bookmark</i>)</div></div>
580 <div class=" item_text " style="margin-left:2em">
581 <p style="margin-top:0em; margin-bottom:0em">
582 This option enlists a directory as a portal and adds all subdirectories
583 as bookmarks. The name of the bookmark is simply the name of the
584 subdirectory. By default the current directory is added as a portal.
585 An optional trailing argument will override this behaviour and
586 instead be interpreted as the portal location.</p>
587 </div>
588 <div style="margin-top:0em">&nbsp;</div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt--try-current-first"></a><b>--try-current-first</b> (<i>try current directory before lookup</i>)</div></div>
589 <div class=" item_text " style="margin-left:2em">
590 <p style="margin-top:0em; margin-bottom:0em">
591 This option is useful in the definition of the <b>to</b> wrapper. Before
592 attempting any lookup of the mark, apparix tests whether the supplied mark
593 exists as a subdirectory in the current directory. If it does,
594 the mark is simply expanded to itself.
595 </p>
596 </div>
597 <div style="margin-top:0em">&nbsp;</div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt--try-current-last"></a><b>--try-current-last</b> (<i>try current directory if lookup fails</i>)</div></div>
598 <div class=" item_text " style="margin-left:2em">
599 <p style="margin-top:0em; margin-bottom:0em">
600 This option is useful in the definition of the <b>to</b> wrapper. If
601 lookup of the mark fails, apparix tests whether the supplied mark
602 exists as a subdirectory in the current directory. If it does,
603 the mark is simply expanded to itself.
604 </p>
605 </div>
606 <div style="margin-top:0em">&nbsp;</div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt--notify-current"></a><b>--notify-current</b> (<i>notify if current directory is used</i>)</div></div>
607 <div class=" item_text " style="margin-left:2em">
608 <p style="margin-top:0em; margin-bottom:0em">
609 This option is useful in the definition of the <i>bf</i> wrapper
610 in conjunction with either <b>--try-current-first</b>
611 or <b>--try-current-last</b>.
612 If the mark is found as a subdirectory in the current directory,
613 apparix notifies the user of this fact (on the diagnostic stream).
614 </p>
615 </div>
616 <div style="margin-top:0em">&nbsp;</div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt-sm"></a><b>-sm</b> &lt;mar&gt; (<i>squash repeated marks</i>)</div></div>
617 <div class=" item_text " style="margin-left:2em">
618 <p style="margin-top:0em; margin-bottom:0em">
619 Apparix will squash bookmarks with mark <tt>&lt;mark&gt;</tt>.
620 This is useful when a mark points to a versioned project, and the
621 project is updated to a new version and a new directory.</p>
622 <p style="margin-bottom:0" class="asd_par">
623 Apparix will by default keep the last one occurring in the resource
624 file (corresponding with <b>-favour</b>&nbsp;<b>O</b>). This option respects the
625 <a class="intern" href="#opt-favour"><b>-favour</b></a> option if given. Duplicating an already existing mark
626 can be useful when it identifies a project for which the underlying
627 directory changes every once in a while (e.g. the project is downloaded from
628 external sources and comes with version information). It is not strictly
629 necessary to squash bookmarks since <b>to</b> functions/macros that are
630 equipped with the <a class="intern" href="#opt-favour"><b>-favour</b></a> option will generally resolve
631 duplicate matches.
632 </p>
633 </div>
634 <div style="margin-top:0em">&nbsp;</div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt-sd"></a><b>-sd</b> &lt;mark&gt; (<i>squash repeated destinations</i>)</div></div>
635 <div class=" item_text " style="margin-left:2em">
636 <p style="margin-top:0em; margin-bottom:0em">
637 All other bookmarks with the same destination as <tt>&lt;mark&gt;</tt> are removed.
638 This is useful when a given destination has acquired multiple
639 bookmarks and you decide to settle on a favourite.
640 </p>
641 </div>
642 <div style="margin-top:0em">&nbsp;</div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt-lm"></a><b>-lm</b> &lt;mark&gt; (<i>list bookmarks with this mark</i>)</div></div>
643 <div class=" item_text " style="margin-left:2em">
644 <p style="margin-top:0em; margin-bottom:0em">
645 It lists all bookmarks <tt>&lt;mark&gt;</tt> (noting that it may point to
646 multiple locations).
647 </p>
648 </div>
649 <div style="margin-top:0em">&nbsp;</div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt-ld"></a><b>-ld</b> &lt;mark&gt; (<i>list repeated destinations</i>)</div></div>
650 <div class=" item_text " style="margin-left:2em">
651 <p style="margin-top:0em; margin-bottom:0em">
652 This lists all bookmarks <tt>&lt;mark&gt;</tt> (noting that it may point to
653 multiple locations) and additionally lists all other bookmarks that share
654 the destination with any of the first bookmarks. This allows one to predict
655 the effect of issuing <tt>apparix -sd &lt;mark&gt;</tt>.
656 </p>
657 </div>
658 <div style="margin-top:0em">&nbsp;</div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt-purge"></a><b>-purge</b> pat (<i>delete bookmarks</i>)</div></div>
659 <div class=" item_text " style="margin-left:2em">
660 <p style="margin-top:0em; margin-bottom:0em">
661 This deletes bookmarks where destination matches <i>pat</i>.
662 All deleted bookmarks are printed to STDOUT. Thus if you regret
663 deleting a bookmark it is easy to add it back. Portal specifications
664 are never affected.</p>
665 </div>
666 <div style="margin-top:0em">&nbsp;</div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt-purge-mark"></a><b>-purge-mark</b> (<i>pat</i>)</div></div>
667 <div class=" item_text " style="margin-left:2em">
668 <p style="margin-top:0em; margin-bottom:0em">
669 This deletes bookmarks where mark matches <i>pat</i>.
670 Portal specifications are never affected.</p>
671 </div>
672 <div style="margin-top:0em">&nbsp;</div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt-d"></a><b>-d</b> (<i>dump resource file to STDOUT</i>)</div></div>
673 <div class=" item_text " style="margin-left:2em">
674 <p style="margin-top:0em; margin-bottom:0em">
675 Dump resource file to STDOUT.</p>
676 </div>
677 <div style="margin-top:0em">&nbsp;</div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt-l"></a><b>-l</b> (<i>list available jumps</i>)</div></div>
678 <div class=" item_text " style="margin-left:2em">
679 <p style="margin-top:0em; margin-bottom:0em">
680 List available jumps paragraph-style. Portal specifications themselves
681 are excluded, and regular jumps and jumps resulting from portal expansions
682 are listed under different headers.</p>
683 </div>
684 <div style="margin-top:0em">&nbsp;</div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt-u"></a><b>-u</b> &lt;num&gt; (<i>remove last &lt;num&gt; additions</i>)</div></div>
685 <div class=" item_text " style="margin-left:2em">
686 <p style="margin-top:0em; margin-bottom:0em">
687 Remove last &lt;num&gt; additions. Portal specifications and regular
688 jumps are treated alike.</p>
689 </div>
690 <div style="margin-top:0em">&nbsp;</div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt--rehash"></a><b>--rehash</b> (<i>re-expand portal bookmarks</i>)</div></div>
691 <div class=" item_text " style="margin-left:2em">
692 <p style="margin-top:0em; margin-bottom:0em">
693 Apparix will reread the resource file and reexpand portal
694 locations. Useful if directories have been added, renamed,
695 or removed. Refer to section <a class="intern" href="#environment">ENVIRONMENT</a> for the effect
696 that the environment variable <tt>APPARIXEXCLUDE</tt> has on portal expansion.</p>
697 </div>
698 <div style="margin-top:0em">&nbsp;</div><div class=" item_cascade item_leftalign nowrap" ><a name="opt-favour"></a><b>-favour</b> &lt;list&gt; (<i>set duplicate resolution policy</i>)</div><div class=" item_cascade item_leftalign nowrap" ><a name="opt-pick"></a><b>-pick</b> &lt;num&gt; (<i>immediate duplicate resolution</i>)</div>
699 <div class=" item_text " style="margin-left:2em">
700 <p style="margin-top:0em; margin-bottom:0em">
701 These options have a section to themselves. Refer to <a class="intern" href="#dup">duplicate resolution</a>.</p>
702 </div>
703 <div style="margin-top:0em">&nbsp;</div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt--cwd"></a><b>--cwd</b> (<i>use getcwd(3), not pwd(1)</i>)</div></div>
704 <div class=" item_text " style="margin-left:2em">
705 <p style="margin-top:0em; margin-bottom:0em">
706 By default aparix uses the program <i>pwd</i>(1) rather than
707 the system call <i>getcwd</i>(3). On some systems it was found
708 that the latter results in paths that contain machine-specific
709 mount components.
710 Appparix will use <i>getcwd</i>(3) when <a class="intern" href="#opt--cwd"><b>--cwd</b></a> is used.</p>
711 </div>
712 <div style="margin-top:0em">&nbsp;</div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt--shell-examples"></a><b>--shell-examples</b> (<i>output example macros</i>)</div></div>
713 <div class=" item_text " style="margin-left:2em">
714 <p style="margin-top:0em; margin-bottom:0em">
715 This outputs example macros. They are also listed in the
716 <a class="intern" href="#files">FILES</a> section though.</p>
717 </div>
718 <div style="margin-top:0em">&nbsp;</div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt--bu"></a><b>--bu</b> (<i>create backup of the resource file</i>)</div></div>
719 <div class=" item_text " style="margin-left:2em">
720 <p style="margin-top:0em; margin-bottom:0em">
721 This creates the backup file in .apparixrc.bu.</p>
722 </div>
723 <div style="margin-top:0em">&nbsp;</div><div class=" item_cascade"><div class=" item_leftalign nowrap " ><a name="opt-bu"></a><b>-bu</b> fname (<i>create backup of the resource file</i>)</div></div>
724 <div class=" item_text " style="margin-left:2em">
725 <p style="margin-top:0em; margin-bottom:0em">
726 This creates the backup file in <i>fname</i>. Use
727 <a class="intern" href="#opt-d"><b>-d</b></a> or <b>-bu</b>&nbsp;<b>-</b> to dump to STDOUT.</p>
728 </div>
729 <div style="margin-top:0em">&nbsp;</div><div class=" item_cascade item_leftalign nowrap" ><a name="opt-h"></a><b>-h</b> (<i>show synopsis</i>)</div><div class=" item_cascade item_leftalign nowrap" ><a name="opt--apropos"></a><b>--apropos</b> (<i>show synopsis</i>)</div>
730 <div class=" item_text " style="margin-left:2em">
731 <p style="margin-top:0em; margin-bottom:0em">
732 print synopsis of all options</p>
733 </div>
734 </div>
735
736 <a name="environment"></a>
737 <h2>ENVIRONMENT</h2>
738 <div class=" itemize " style="margin-top:1em; font-size:100%">
739 <div class=" item_cascade"><div class=" item_leftalign nowrap " >APPARIXEXCLUDE</div></div>
740 <div class=" item_text " style="margin-left:2em">
741 <p style="margin-top:0em; margin-bottom:0em">
742 This variable specifies exclusion behaviour
743 when portals are expanded with the <tt>--rehash</tt> option.
744 It has the following syntax:
745 </p>
746 <div class="verbatim"> &lt;[:,][&lt;string&gt;]&gt;+</div>
747 <p style="margin-top:0em; margin-bottom:0em">
748 That is, a list of names with each name preceded by a colon or a comma.
749 A colon indicates that <tt>&lt;string&gt;</tt> triggers exclusion of directory names
750 for which the trailing component is identical to <tt>&lt;string&gt;</tt>.
751 A comma indicates that <tt>&lt;string&gt;</tt> triggers exclusion of directory names
752 for which the trailing component contains <tt>&lt;string&gt;</tt> as a substring.
753 Consider:
754 </p>
755 <div class="verbatim"> export APPARIXEXCLUDE=:CVS:lib,tmp # A - example
756 export APPARIXEXCLUDE=, # B - curiosity</div>
757 <p style="margin-top:0em; margin-bottom:0em">
758 The first excludes directory names <tt>CVS</tt> and <tt>lib</tt> and any directory
759 name having <tt>tmp</tt> as a substring.
760 The second example will effectively disable portals,
761 as it speficies the empty string which is a substring of all strings.
762 </p>
763 </div>
764 <div style="margin-top:0em">&nbsp;</div><div class=" item_cascade"><div class=" item_leftalign nowrap " >APPARIXTAG</div></div>
765 <div class=" item_text " style="margin-left:2em">
766 <p style="margin-top:0em; margin-bottom:0em">
767 This variable, if set, is incorporated into the names of the
768 apparix resource files. By default these are <tt>.apparixrc</tt> and <tt>.apparixexpand</tt>.
769 When APPARIXTAG is set to <tt>&lt;tag&gt;</tt> they become <tt>.&lt;tag&gt;apparixrc</tt> and
770 <tt>.&lt;tag&gt;apparixexpand</tt>.
771 This can be used e.g. to maintain different sets of bookmarks on different
772 host machines.
773 </p>
774 </div>
775 <div style="margin-top:0em">&nbsp;</div><div class=" item_cascade"><div class=" item_leftalign nowrap " >APPARIXLOG</div></div>
776 <div class=" item_text " style="margin-left:2em">
777 <p style="margin-top:0em; margin-bottom:0em">
778 This variable, if set, is interpreted as the name of a log file.
779 The log file keeps track of all newly added bookmarks and
780 portals without ever deleting anything, in the same format
781 as the <tt>.apparixrc</tt> file. If this variable is not set
782 nothing is tracked.
783 </p>
784 </div>
785 <div style="margin-top:0em">&nbsp;</div><div class=" item_cascade"><div class=" item_leftalign nowrap " >APPARIXPURGE</div></div>
786 <div class=" item_text " style="margin-left:2em">
787 <p style="margin-top:0em; margin-bottom:0em">
788 This changes the way apparix dumps purged bookmarks to STDOUT.
789 By default they are dumped as command lines that will reimport
790 the bookmarks if issued (i.e. cut and pasted).
791 By setting this variable to 1 purged bookmarks are dumped
792 in the format used in the <tt>.apparixrc</tt> file.
793 </p>
794 </div>
795 </div>
796
797 <a name="files"></a>
798 <h2>FILES</h2>
799 <p style="margin-bottom:0" class="asd_par">
800 You should use aliases or functions to make apparix really useful.
801 Get them from apparix by giving it the --shell-examples option,
802 or from further below.
803 Note the fragment that provides <b>to</b> argument completion in bash.
804 </p>
805 <div class=" itemize " style="margin-top:1em; font-size:100%">
806 <div class=" item_cascade"><div class=" item_leftalign nowrap " >$HOME/.apparixrc</div></div>
807 <div class=" item_text " style="margin-left:2em">
808 <p style="margin-top:0em; margin-bottom:0em">This is the primary resource file. There is usually no
809 need to edit it by hand. Sometimes it can be useful to edit
810 by hand to remove an unwanted bookmark; refer to <a class="intern" href="#edit">editing bookmarks</a>.</p>
811 </div>
812 <div style="margin-top:0em">&nbsp;</div><div class=" item_cascade"><div class=" item_leftalign nowrap " >$HOME/.apparixrc.bu</div></div>
813 <div class=" item_text " style="margin-left:2em">
814 <p style="margin-top:0em; margin-bottom:0em">
815 Apparix creates a back-up file whenever it is asked to
816 remove entries from it. Refer
817 to <a class="intern" href="#edit">editing bookmarks</a> for options inducing removal.
818 You can explicitly require a backup to be made by
819 either of <a class="intern" href="#opt--bu"><b>--bu</b></a> or <a class="intern" href="#opt-bu"><b>-bu</b>&nbsp;<i>fname</i></a>.</p>
820 </div>
821 <div style="margin-top:0em">&nbsp;</div><div class=" item_cascade"><div class=" item_leftalign nowrap " >$HOME/.apparixexpand</div></div>
822 <div class=" item_text " style="margin-left:2em">
823 <p style="margin-top:0em; margin-bottom:0em">
824 This contains bookmarks that are expanded from portals.
825 A portal is simply some directory. The names of all subdirectories
826 are taken as bookmarks that point to those subdirectories.
827 This file can be recreated by issuing</p>
828 <div class="verbatim">apparix --rehash</div>
829 </div>
830 <div style="margin-top:0em">&nbsp;</div><div class=" item_cascade item_leftalign nowrap" >$HOME/.bashrc</div><div class=" item_cascade item_leftalign nowrap" >$HOME/.tcshrc</div><div class=" item_cascade item_leftalign nowrap" >$HOME/.cshrc</div>
831 <div class=" item_text " style="margin-left:2em">
832 <p style="margin-top:0em; margin-bottom:0em">
833 Add the code you need to the appropriate rc file. The macros and functions
834 below point <i>cd</i>(1) in the right direction.</p>
835 </div>
836 </div>
837 <div class="verbatim">BASH-style functions
838 ---
839 function to () {
840 if test "$2"; then
841 cd "$(apparix --try-current-first -favour rOl "$1" "$2" || echo .)"
842 elif test "$1"; then
843 if test "$1" == '-'; then
844 cd -
845 else
846 cd "$(apparix --try-current-first -favour rOl "$1" || echo .)"
847 fi
848 else
849 cd $HOME
850 fi
851 }
852 function bm () {
853 if test "$2"; then
854 apparix --add-mark "$1" "$2";
855 elif test "$1"; then
856 apparix --add-mark "$1";
857 else
858 apparix --add-mark;
859 fi
860 }
861 function portal () {
862 if test "$1"; then
863 apparix --add-portal "$1";
864 else
865 apparix --add-portal;
866 fi
867 }
868 # function to generate list of completions from .apparixrc
869 function _apparix_aliases ()
870 { cur=$2
871 dir=$3
872 COMPREPLY=()
873 nullglobsa=$(shopt -p nullglob)
874 shopt -s nullglob
875 if let $(($COMP_CWORD == 1)); then
876 # now cur=&lt;apparix mark&gt; (completing on this) and dir='to'
877 # Below will not complete on subdirectories. swap if so desired.
878 # COMPREPLY=( $( cat $HOME/.apparix{rc,expand} | grep "j,.*$cur.*," | cut -f2 -d, ) )
879 COMPREPLY=( $( (cat $HOME/.apparix{rc,expand} | grep "\&lt;j," | cut -f2 -d, ; ls -1p | grep '/$' | tr -d /) | grep "\&lt;$cur.*" ) )
880 else
881 # now dir=&lt;apparix mark&gt; and cur=&lt;subdirectory-of-mark&gt; (completing on this)
882 dir=`apparix --try-current-first -favour rOl $dir 2&gt;/dev/null` || return 0
883 eval_compreply="COMPREPLY=( $(
884 cd "$dir"
885 \ls -d $cur* | while read r
886 do
887 [[ -d "$r" ]] &amp;&amp;
888 [[ $r == *$cur* ]] &amp;&amp;
889 echo \"${r// /\\ }\"
890 done
891 ) )"
892 eval $eval_compreply
893 fi
894 $nullglobsa
895 return 0
896 }
897 # command to register the above to expand when the 'to' command's args are
898 # being expanded
899 complete -F _apparix_aliases to
900 ---
901 CSH-style aliases
902 ---
903 # The outcommented alias does not supplant cd, the other one does.
904 # alias to 'cd `(apparix -favour rOl \!* || echo -n .)`'
905 alias to '(test "x-" = "x\!*") &amp;&amp; cd - || (test "x" != "x\!*") &amp;&amp; cd `(apparix --try-current-first -favour rOl \!* || echo -n .)` || cd'
906 alias bm 'apparix --add-mark \!*'
907 alias portal 'apparix --add-portal \!*'
908 ---</div>
909 <p style="margin-bottom:0" class="asd_par">More elaborate setups are possible. This CSH-style alias:</p>
910 <div class="verbatim">alias to '(test "x" != "x\!*") &amp;&amp; cd `(apparix -favour rOl \!* || echo -n .)` || apparix -l'</div>
911 <p style="margin-bottom:0" class="asd_par">lists all available jumps if invoked without arguments.</p>
912
913 <a name="notes"></a>
914 <h2>NOTES</h2>
915 <p style="margin-bottom:0" class="asd_par">
916 Below follow some comments on other approaches to file system navigation.
917 <a class="intern" href="#history">HISTORY</a> explains the difference between the venerable <b>cdargs</b>
918 program and <b>apparix</b>.
919 </p>
920 <p style="margin-bottom:0" class="asd_par">
921 CDPATH is only useful in cases where a given directory has subdirectories
922 with distinctive names. It does not usually scale well when there are
923 more than a few paths in CDPATH.
924 </p>
925 <p style="margin-bottom:0" class="asd_par">
926 Some people use aliases to jump to often visited directories.
927 I was one of them for a period of ten years. The fact is,
928 those aliases are cumbersome to create and remove and they
929 clutter up the alias namespace. They can clash with
930 executable names when the alias includes the <i>cd</i> part. This sometimes
931 prohibits one from assigning the logical bookmark to a given
932 location, especially when one has a lot of source code locations.
933 They can clash with directory names when
934 the aliases just expand to the location. This again means that
935 sometimes a location cannot be assigned its logical bookmark.
936 I have found that setting <i>cd</i> jumps aside in their own namespace
937 improves file system navigation by a large factor.
938 </p>
939 <p style="margin-bottom:0" class="asd_par">
940 It is also possible to create symlinks to often
941 visited files. Again, creation and removal of these are cumbersome.
942 One could of course create shell functions with a similar interface
943 to apparix or cdargs to handle the symlink lifecycle.
944 On Linux Weekly News <i>nix</i> suggested to put these symlinks
945 in a single directory and add that directory to CDPATH.
946 This is quite a neat trick and effectively creates a bookmark
947 navigation system.
948 </p>
949 <p style="margin-bottom:0" class="asd_par">
950 Still there are problems with the above approach.
951 One problem with the symlink approach is that they are a bit
952 awkward to edit. One could make a utility to wrap around the problem,
953 but in the end the directory-with-symlinks would
954 functionally be the same as apparix's <b>.apparixrc</b> resource file,
955 only more of a kludge.
956 Another problem is that symlinks are awkard when traversing
957 the file system. They confuse the notion of parent directory
958 and '<tt>cd ..</tt>' mostly does the unexpected. Sometimes '<tt>..</tt>'
959 has a different meaning to <b>cd</b> than it has to another application,
960 as one will trace back symlinks and the other will not.
961 Finally, a minor objection
962 is that I find it convenient to have bookmarks in a separate
963 namespace than that of <i>cd</i>(1). Jumps are magical and it is
964 natural to invoke them by a different method. This is in fact
965 how apparix acquired its CDPATH behaviour. I used CDPATH to
966 jump to a few particular source directories with distinct names
967 that lay deeply hidden in some CVS directory. Once I started using
968 apparix however, I would mistakenly issue <i>to</i> rather than <i>cd</i>
969 to jump to those locations. My brain classified both types of jump
970 in the same category.
971 </p>
972 <p style="margin-bottom:0" class="asd_par">
973 Apparix (and cdargs) have another use besides jumping, namely
974 annotation. Whenever I end up in an esoteric part of the file system and
975 need to make a quick note of the location, I simply bookmark it.
976 </p>
977 <p style="margin-bottom:0" class="asd_par">
978 On SlashDot, that eternal source of wisdom or alternatively
979 the geek wheel of suffering, Clueless Moron offered the following gems.</p>
980 <div class="verbatim"> mk() { eval ${1:-MKPWD}=\"`pwd`\"; }
981 rt() { eval cd \"\$${1:-MKPWD}\";pwd; }
982
983 # type "mk" (as in "mark") and "rt" (as in "return") to mark
984 # a directory and later go back to it.
985 # Or give it a name: do "mk foo", and later on "rt foo"</div>
986 <p style="margin-bottom:0" class="asd_par">
987 This of course is a per-session mechanism, but noteworthy
988 for its simplicity. I am not sure whether csh-style shells
989 could offer an equivalent.</p>
990 <p style="margin-bottom:0" class="asd_par">
991 A feature shared by apparix and cdargs is that adding a bookmark
992 immediately takes effect in all shells. There is no need to
•993 source some resource file, as the applications do this every time
994 they are invoked. It is fast, do not worry.
995 </p>
996
997 <a name="bugs"></a>
998 <h2>BUGS</h2>
999 <p style="margin-top:0em; margin-bottom:0em">
1000 The resource file parsing code thinks that parentheses are special.
1001 Also records are currently separated by commas. Accordingly, apparix will
1002 hitch if a path name contains a parenthesis or a comma.</p>
1003
1004 <a name="author"></a>
1005 <h2>AUTHOR</h2>
1006 <p style="margin-top:0em; margin-bottom:0em">
1007 Stijn van Dongen.</p>
1008
1009 <a name="thanks"></a>
1010 <h2>THANKS</h2>
1011 <p style="margin-bottom:0" class="asd_par">
1012 Stefan Kamphausen wrote <b>cdargs</b>, the inspiration for apparix.</p>
1013 <p style="margin-bottom:0" class="asd_par">
1014 Sitaram Chamarty fixed up some of the existing bash code, and added the tab
1015 completion part (basing this on similar code in cdargs). He does not
1016 garantuee predictable or even pretty results if there are spaces in the
1017 directory names which you attempt to complete. <a class="intern" href="#author">AUTHOR</a> would like
1018 to submit that spaces in path names are evil, and that the completion code
1019 seems to work in their evil presence anyway. Just <a class="intern" href="#bugs">don't put
1020 commas</a> in path names.
1021 </p>
1022 <p style="margin-bottom:0" class="asd_par">
1023 The autotooled build environment was modified from a template written
1024 by Joost van Baal.
1025 </p>
1026 <p style="margin-bottom:0" class="asd_par">
1027 Several people suggested to enable apparix to merge accessible directories
1028 and marks, but Matias Piipari phrased it the most convincingly.
1029 </p>
1030
1031 <a name="history"></a>
1032 <h2>HISTORY</h2>
1033 <p style="margin-bottom:0" class="asd_par">
1034 Apparix was created to optimize a scenario that
1035 <a target="_parent" class="extern" href="http://www.skamphausen.de/cgi-bin/ska/CDargs">cdargs</a> does not support
1036 very well, namely where the mark (called <i>needle</i> in cdargs) is always
1037 known. As additional features apparix supports CDPATH-style behaviour,
1038 derived subdirectory specification, and transparent treatment of bookmarks
1039 and directories, all integrated with bash tab completion. In other respects
1040 apparix is a much simpler application. <b>cdargs</b> offers menu-based
1041 navigation of the file system and the bookmark list, which apparix does not.
1042 </p>
1043 </body>
1044 </html>