Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Adding README

  • Loading branch information...
commit 3b1b53a848d4d7599984aa439a0df52786e643cf 1 parent fc8a452
Mark Hepburn authored September 14, 2009

Showing 1 changed file with 81 additions and 0 deletions. Show diff stats Hide diff stats

  1. 81  README.md
81  README.md
Source Rendered
... ...
@@ -0,0 +1,81 @@
  1
+Tags History Browsing
  2
+=====================
  3
+
  4
+Overview
  5
+--------
  6
+
  7
+This package offers functionality to supplement the different tags
  8
+operations, usually bound to M-./M-\*.  It currently supports etags.el
  9
+and gtags.el, and should be easily extendable to other backends.
  10
+
  11
+As you navigate through a source tree it can become easy to forget how
  12
+you got to your current location -- you could call M-\* repeatedly to
  13
+pop back up the stack, but this would lose your current location.
  14
+This module allows you to view the path taken, and if desired to jump
  15
+immediately back to any intermediate location, delete any extranous
  16
+locations, etc.
  17
+
  18
+I wrote this for my own use, and my own amusement -- typically I'll
  19
+think about writing something for emacs, then have a quick hunt and
  20
+find something that already does the job.  This time I followed
  21
+through to completion, but if you're after an alternative when I did
  22
+go looking I found
  23
+[http://www.emacswiki.org/emacs/EtagsStack]()
  24
+I'd like to think this offers a little bit different; it supports
  25
+gtags as well out of the box and in theory at least can be extended to
  26
+others, and it offers a few more operations on the chronological
  27
+trace.  Of course, if you need any of that is up to you :)
  28
+
  29
+The functionality and interface is inspired by browse-kill-ring (and
  30
+in fact, I borrowed the navigation code from that package).
  31
+
  32
+Installation and Usage:
  33
+-----------------------
  34
+
  35
+Setup:
  36
+
  37
+* clone the repository, or just copy tags-view.el somewhere
  38
+* Make sure it is in your path: `(add-to-list load-path checkout-location)`
  39
+
  40
+When you want to use it, make sure that it is loaded
  41
+(`(require 'tags-view)` or similar), then call `M-x tv-view-history`.
  42
+
  43
+This will pop open a buffer with your tag locations displayed,
  44
+optionally with surrounding lines of context from their source files,
  45
+with the most recent at the top.  Type `C-h m` to see what commands
  46
+are available, but in summary:
  47
+
  48
+* `n` and `p` navigate down and up the list;
  49
+* RETURN closes the history buffer and jumps to that location (without
  50
+  alterating the tags stack);
  51
+* `o` displays the tag under point in another window, without leaving
  52
+  the history buffer (useful to get greater context as you browse);
  53
+* `d` will delete the tag under point from the stack (useful if you
  54
+  only want to think about a few key functions in the trace).
  55
+
  56
+Customising:
  57
+------------
  58
+
  59
+The most likely variable you are going to want to customise is
  60
+`tv-context-lines`, which defaults to 0 -- this is the number of lines
  61
+of context displayed before and after the actual location of each tag.
  62
+
  63
+The algorithm for determining which of etags, gtags etc is currently
  64
+in use is just to start either from the directory of the current
  65
+buffer (or `pwd` if no file is associated when you invoke it), then
  66
+search upwards until it finds one of TAGS or GTAGS (with preference
  67
+for the latter).  You can customise this with your own algorithm
  68
+though by setting `tv-determine-backend-function`, which should be a
  69
+function of no arguments that returns a symbol denoting the backend to
  70
+use (eg, `'etags`), or `'none` if nothing can be determined.
  71
+
  72
+If you want to add another backend you want to look at at the previous
  73
+function, and also `tv-backend-list`, whose format is documented in
  74
+the variable itself.  Currently this just involves specifying
  75
+functions to return the list of data structures (buffer/position) for
  76
+the backend, and to delete a stack location if requested.
  77
+
  78
+Bugs:
  79
+-----
  80
+
  81
+Bound to be heaps.  Does anyone want to write some tests?

0 notes on commit 3b1b53a

Please sign in to comment.
Something went wrong with that request. Please try again.