README
1==========
2GeanyCtags
3==========
4
5.. contents::
6
7About
8=====
9
10GeanyCtags adds a simple support for generating and querying ctags files for a Geany
11project. It requires that the ctags command is installed in a system path. On
12unix systems, distributions usually provide the ctags package; on Windows, the
13ctags binary can be found in the zip Windows distribution from the ctags home
14page (http://ctags.sourceforge.net).
15
16Even though Geany supports symbol definition searching by itself within the open files
17(and with a plugin support within the whole project), tag regeneration can become
18too slow for really big projects. This is why this plugin was created. It makes
19it possible to generate the tag file only once and just query it when searching
20for a particular symbol definition/declaration. This approach is fine for big projects
21where most of the codebase remains unchanged and the tag positions remain more
22or less static.
23
24Usage
25=====
26
27GeanyCtags only works for Geany projects so in order to use it, a Geany project
28has to be open. The "File patterns" entry under Project->Properties determines
29for which files the tag list will be generated. All files within the project base
30path satisfying the file patterns will be included for the tag generation.
31
32Tag Generation
33--------------
34
35To generate the list of tags, make sure that
36
37* a project is open, and
38* "File patterns" are specified correctly under Project->Properties
39
40Then, select Project->Generate tags. After this, a file whose name corresponds to
41the project name with the suffix ".tags" is created in the same directory as the
42project file.
43
44Tag Querying
45------------
46
47There are two ways to find a symbol's definition/declaration:
48
49* using the context menu by placing a cursor at the searched symbol, right-clicking
50 and selecting one of the two top items "Find Tag Definition" or "Find Tag Declaration".
51* using Project->Find tag
52
53If the symbol is found, the editor is opened at the tag line. In addition, all the
54found tags are written into the Messages window. This is useful when there are more
55tags of the same name - by clicking a line in the Messages window it is possible
56to jump to any of the found tags.
57
58When using the Project->Find tag search, it is possible to select from several
59search types:
60
61* prefix (default) - finds all tags with the specified prefix
62* exact - finds all tags matching the name exactly
63* pattern - finds all tags matching the provided glob pattern
64
65Note that the pattern option is the slowest of the three possibilities because it
66has to go through the tag list sequentially instead of using binary search used
67by the other two methods. By default, tag definitions are searched; to search tag
68declarations, select the Declaration option.
69
70Known issues
71============
72
73* Right now it's not possible to just right-click the searched symbol in the editor
74 and search for definition/declaration - first, a cursor has to be placed at
75 the symbol. This is because at the moment the necessary functionality to do this
76 is private in Geany and not exported to plugins so it cannot be implemented.
77 I will try to get the necessary functions public in Geany to make it possible
78 in the future.
79* Under Windows, GeanyCtags generates tags for all the files within the project base
80 path instead of just the files defined by the patterns. This happens because
81 of the missing (or at least not normally installed) find command used under
82 unix systems to restrict the file list to those matching the patterns. It
83 would be possible to perform the filtering manually but frankly I'm rather lazy
84 to do so (and don't have Windows installed to test). Patches are welcome.
85
86License
87=======
88
89GeanyCtags is distributed under the terms of the GNU General Public License
90as published by the Free Software Foundation; either version 2 of the
91License, or (at your option) any later version. A copy of this license
92can be found in the file COPYING included with the source code of this
93program.
94
95Downloads
96=========
97
98GeanyCtags is part of the combined Geany Plugins release.
99For more information and downloads, please visit
100http://plugins.geany.org/geany-plugins/
101
102Development Code
103================
104
105Get the code from::
106
107 git clone https://github.com/geany/geany-plugins.git
108
109Ideas, questions, patches and bug reports
110=========================================
111
112Please direct all questions, bug reports and patches to the plugin author using the
113email address listed below or to the Geany mailing list to get some help from other
114Geany users.
115
1162010-2014 by Jiří Techet
117techet(at)gmail(dot)com
118