/plugins/Tags/tags/tags-rel-1-0-6/Tags.html

# · HTML · 353 lines · 298 code · 55 blank · 0 comment · 0 complexity · 002c8f38f68b41b53415a7457557642e MD5 · raw file 

    

  1. <html>
    2. 

  2. <head>
    3. 

  3. <title>Tags plugin</title>
    4. 

  4. </head>
    5. 

  5. <body bgcolor="#FFFFFF">
    6. 

  6. 

  7. 

  8. <table
    9. 

  9.     bgcolor="#CCCCFF"
    10. 

  10.     border="0"
    11. 

  11.     cellspacing="0"
    12. 

  12.     cellpadding="3"
    13. 

  13.     width="100%"
    14. 

  14.     summary="Tags page header"
    15. 

  15. >
    16. 

  16.     <tr width="100%">
    17. 

  17.     <td><big><big>Tags plugin</big></big></td>
    18. 

  18.     <td align="right"><small>By Kenrick Drew<br>
    19. 

  19.     <em>kdrew@earthlink.net</em></small></td></tr>
    20. 

  20. </table>
    21. 

  21. 

  22. 

  23. <ul>
    24. 

  24.     <li><a href="#introduction">Introduction</a></li>
    25. 

  25.     <li><a href="#creating_tag_files">Creating Tag Index Files</a></li>
    26. 

  26.     <li><a href="#usage">Usage</a></li>
    27. 

  27.     <ul>
    28. 

  28.           <li><a href="#tagging">Tag jumping</a></li>
    29. 

  29.           <li><a href="#tag_stack">The tag stack</a></li>
    30. 

  30.           <li><a href="#tag_collisions">Tag collisions</a></li>
    31. 

  31.     </ul>
    32. 

  32.     <li><a href="#config">Configuration</a></li>
    33. 

  33.     <li><a href="#shortcuts">Suggested Keyboard shortcuts and UI</a></li>
    34. 

  34.     <li><a href="#finding">Where to find the ctags program</a></li>
    35. 

  35.     <li><a href="#lincense">Lincense</a></li>
    36. 

  36.     <li><a href="#bugs">Known Bugs/Limitations</a></li>
    37. 

  37.     <li><a href="#todo">Future Directions</a></li>
    38. 

  38.     <li><a href="#feedback">Feedback</a></li>
    39. 

  39.     <li><a href="#credits">Credits</a></li>
    40. 

  40.     <li><a href="#changelog">Changelog</a></li>
    41. 

  41. </ul>
    42. 

  42. 

  43. <h2><a name="introduction">Introduction</a></h2>
    44. 

  44. <p>
    45. 

  45. The Tags plugin allows a user to jump to the definition of a specific language
    46. 

  46. object or "tag" using tag index files. For example, in C programs, the user can
    47. 

  47. immediatly jump to the definition of a desired function or data structure
    48. 

  48. without having to know where or what file it is defined. Tag jumping can be
    49. 

  49. accomplished by either selecting the desired tag, placing the cursor on the
    50. 

  50. tag, or entering the tag.
    51. 

  51. </p>
    52. 

  52. <p>
    53. 

  53. The tag index files are created by the "<a href="#finding">ctags</a>" program 
    54. 

  54. of which there are several versions.  ctags can be found on most UNIX systems.  
    55. 

  55. The Exuberant C Tags program has both UNIX and Windows versions.
    56. 

  56. </p>
    57. 

  57. 

  58. <h2><a name="creating_tag_files">Creating Tag Index Files</a></h2>
    59. 

  59. <p>
    60. 

  60. Without tag index files the Tags plugin is useless. Well, not necessarily
    61. 

  61. useless; it will let you know it can't find or jump to anything which can be of
    62. 

  62. some use. Tag files are created with the ctags program.
    63. 

  63. </p>
    64. 

  64. <p>
    65. 

  65. For more extensive help on the ctags program see the documentation that comes
    66. 

  66. with your distribution (man pages, readme files).  But, in general you can
    67. 

  67. create tag index files with the Exuberant C Tag commands:
    68. 

  68. </p>
    69. 

  69. <pre>
    70. 

  70.      ctags *     create a tag file in the current directory for all recognized 
    71. 

  71.                  source files
    72. 

  72.      ctags -R    create a tag file in the current directory for all files in 
    73. 

  73.                  an entire source directory tree.
    74. 

  74. </pre>
    75. 

  75. <p>
    76. 

  76. Please note that the tag index files list definition file names based on path
    77. 

  77. that you pass to the ctags program.  If you don't pass the full path of the 
    78. 

  78. files to ctags, the definition file names listed in the tag index file will be
    79. 

  79. relative to the current directory.  If this is not desired you can pass $cwd or
    80. 

  80. `pwd` to ctags:
    81. 

  81. </p>
    82. 

  82. <pre>
    83. 

  83.      ctags $cwd/*
    84. 

  84.      ctags -R $cwd
    85. 

  85. </pre>
    86. 

  86. <p>
    87. 

  87. Tag index files are search using a binary search, so tag index files must be 
    88. 

  88. sorted.
    89. 

  89. </p>
    90. 

    91. 

  91. <h2><a name="usage">Usage</a></h2>
    92. 

    93. 

  93. <h3><a name="tagging">Tag jumping</a></h3>
    94. 

  94. <p>
    95. 

  95. There are 2 ways to jump to a desired tag:
    96. 

    97. 

  97. <ol>
    98. 

  98.   <li>Place the cursor on or select the desired tag.  From the Plugins > Tags 
    99. 

  99.   menu use "Follow Tag".  "Follow Tag (New View)" will jump to a tag
    100. 

  100.   in a new view.</li>
    101. 

    102. 

  102. 	<li>From the Plugins > Tags menu use "Follow Tag..." which will prompt you for
    103. 

  103. 	the desired tag. The "Open new view" checkbox will jump to the entered tag in
    104. 

  104. 	an new view.</li>
    105. 

  105. </ol>
    106. 

  106.     
    107. 

  107. </p>
    108. 

    109. 

  109. <h3><a name="tag_stack">The tag stack</a></h3>
    110. 

  110. <p>
    111. 

  111. Once you have jumped to a tag, your previous position is remembered with the
    112. 

  112. tag stack.  You can return to your previous position from the Plugins > Tags
    113. 

  113. menu using "Pop Tag".  Currently the stack is a global stack.
    114. 

  114. </p>
    115. 

    116. 

  116. <h3><a name="tag_collisions">Tag collisions</a></h3>
    117. 

    118. 

  118. <p> A tag collision can occur when there is more than one defintion for a
    119. 

  119. specific tag as defined in the tag index files. This especially occurs on
    120. 

  120. object oriented programming languages, and local projects where you are using a
    121. 

  121. global system tag index file along with a local tag index file. To easily
    122. 

  122. facilitate tag collisions, if more than one tag is found in the tag index
    123. 

  123. files, you are presented, located under the cursor, a list of choices.
    124. 

  124. Differentation between the tags is currently only done by tag defintion file
    125. 

  125. names. You can select the desired tag by either using the mouse, keyboard arrow
    126. 

  126. keys or number keys (1 - 9 only). The tag collision list can be dismissed with
    127. 

  127. the Escape (Esc) key. </p>
    128. 

    129. 

  129. <h2><a name="config">Configuration</a></h2>
    130. 

    131. 

  131. <p>The Tags plugin can be configured under the Plugin Options node of the Global 
    132. 

  132. Options dialog.</p>
    133. 

    134. 

  134. <p>Search tag file in current buffer's directory: Check this option if
    135. 

  135. you want the tag search to start with the tag index file (./tags) in the
    136. 

  136. buffer's directory. The tag index file doesn't need to be in the tag index
    137. 

  137. search file list. If it is it will be skipped.</p>
    138. 

    139. 

  139. <p>Tag index file name:  If you have configured Tags to use the tag index file
    140. 

  140. in the current buffer's directory you can change the file named that the plugin
    141. 

  141. looks for.  The default is "tags".</p>
    142. 

    143. 

  143. <p>If tag match is found continue searching subsequent tag index files:  By 
    144. 

  144. default, the first matching tag (or groups of tags if
    145. 

  145. a tag collision occurs) found will stop the search. Using this option will
    146. 

  146. allow all tag files to be searched.</p>
    147. 

    148. 

  148. <p>Tag search files (in order of search):  Add tag index files that should be 
    149. 

  149. searched to this list.  The order of the list is the search order.</p>
    150. 

    151. 

  151. <h2><a name="shortcuts">Suggested Keyboard shortcuts and UI</a></h2>
    152. 

    153. 

  153. <p>Here are some suggested key bindings.  These do stomp on some JEdit key
    154. 

  154. bindings, but I find that they work well.  They are based on the vi (and it's
    155. 

  155. clones) key bindings for tagging.</p>
    156. 

    157. 

  157. <pre>
    158. 

  158.      Follow Tag:             Ctrl + ]
    159. 

  159.      Follow Tag (New View):  Ctrl + SHIFT + ]     
    160. 

  160.      Follow Tag...:          Alt + ]     
    161. 

  161.      Pop Tag:                Ctrl + T
    162. 

  162. </pre>
    163. 

    164. 

  164. <p>Keyboard shortcuts can be defined under the Shortcuts node of the Global
    165. 

  165. Options dialog.</p>
    166. 

    167. 

  167. <p>Also one can place the tagging commands in the Context Menu.  Context menu
    168. 

  168. items can be defined under the Context Menu node of the Global Options dialog.
    169. 

  169. </p>
    170. 

    171. 

  171. <h2><a name="finding">Where to find the ctags program</a></h2>
    172. 

  172. <p>You can find the Exuberant C Tags program at:</p>
    173. 

    174. 

  174. <pre>
    175. 

  175.    <a href="http://ctags.sourceforge.net">http://ctags.sourceforge.net</a>
    176. 

  176. </pre>
    177. 

    178. 

  178. <p>Exuberant C Tags is also included in the  
    179. 

  179. <a href="http://sources.redhat.com/cygwin/">cygwin</a> distribution for 
    180. 

  180. Windows.  I highly recommend cygwin.</p>
    181. 

    182. 

  182. <p>You can also use the standard UNIX ctags program, or the GNU C Tags program,
    183. 

  183. but you'll find that Exuberant C Tags provides a bit more info (or too much
    184. 

  184. depending on how much of a minimalist you are).</p>
    185. 

    186. 

  186. <h2><a name="lincense">Lincense</a></h2>
    187. 

  187. <p>
    188. 

  188. The source code is distributed under the GPL. Please see
    189. 

  189. <a href="http://www.fsf.org/copyleft/gpl.html">http://www.fsf.org/copyleft/gpl.html</a>
    190. 

  190. </p>
    191. 

    192. 

  192. <h2><a name="bugs">Known Bugs/Limitations</a></h2>
    193. 

  193. <ul>
    194. 

    195. 

  195. <li>Has only been tested in C and Java.</li>
    196. 

    197. 

  197. <li>Tag files *MUST* be sorted. Else, the tag will probably never be found b/c we
    198. 

  198. are using a binary searching mechanism.</li>
    199. 

    200. 

  200. <li>Bachward searching patterns (?...?) are not supported.</li>
    201. 

    202. 

  202. </ul>
    203. 

    204. 

  204. <h2><a name="todo">Future Directions</a></h2>
    205. 

  205. <p>
    206. 

  206. See <a href="./TODO.TXT">TODO.TXT</a>
    207. 

  207. </p>
    208. 

    209. 

  209. <h2><a name="feedback">Feedback</a></h2>
    210. 

  210. <p>
    211. 

  211. The preferred way to send bug reports or feature requests is to use the
    212. 

  212. Sourceforge Bug Tracker at
    213. 

  213. <a href="http://sourceforge.net/bugs/?group_id=588">http://sourceforge.net/bugs/?group_id=588</a>.
    214. 

  214. </p>
    215. 

  215. <p>You can also write to:</p>
    216. 

  216. <ul>
    217. 

  217.     <li>jEdit-users mailing-list <em>&lt;jedit-users@lists.sourceforge.net&gt;</em>;</li>
    218. 

  218.     <li>jEdit-devel mailing.list <em>&lt;jedit-devel@lists.sourceforge.net&gt;</em>.</li>
    219. 

  219. </ul>
    220. 

    221. 

  221. <h2><a name="credits">Credits</a></h2>
    222. 

  222. <ul>
    223. 

  223.   <li>Vim reference manual (Bram Moolenaar)</li>
    224. 

  224.   <li>Exuberant C Tags man page (Darren Hiebert)</li>
    225. 

  225. </ul>
    226. 

    227. 

  227. <h2><a name="changelog">Changelog</a></h2>
    228. 

  228. <ul>
    229. 

    230. 

  230. 	<li>Version 1.0.6, bug fixes (Feb 2002)</li>
    231. 

  231.   <ul>
    232. 

  232.     <li>Fixed bug where the escape character '\' was showing up in the user
    233. 

  233.         visible search string.</li>
    234. 

  234.     <li>Used JEditTextArea.offsetToXY() to position popup within folded, and
    235. 

  235.         wrapped text.</li>
    236. 

  236.     <li>Requires java 1.3<\li>
    237. 

  237.     <li>Requires JEdit 4.0<\li>    
    238. 

  238.   </ul>
    239. 

    240. 

  240. 	<li>Version 1.0.3, update (Nov 2001)</li>
    241. 

  241.   <ul>
    242. 

  242.     <li>Replaced Macros.error with GUIUtilities.error.</li>
    243. 

  243.   </ul>
    244. 

    245. 

  245. 	<li>Version 1.0.2, bug fixes (Nov 2001)</li>
    246. 

  246.   <ul>
    247. 

  247.     <li>Fixed bug where if you removed tag index files from the search the code
    248. 

  248.         would remember the later entries.</li>
    249. 

  249.     <li>Fixed bug where searching for tag search string in file was using the
    250. 

  250.         search file set.</li>
    251. 

  251.     <li>Fixed bug in option panel where changes to the list of tag index files
    252. 

  252.         were always committed even if you pressed "Cancel".</li>
    253. 

  253.     <li>Fixed exuberant tag info display when mixed tag files are used.</li>
    254. 

  254.     <li>Removed directions from COPYING.</li>
    255. 

  255.     <li>Added some initial user hidden development code.</li>
    256. 

  256.   </ul>
    257. 

    258. 

  258. 	<li>Version 1.0.1, bug fixes (Nov 2001)</li>
    259. 

  259.   <ul>
    260. 

  260.     <li>Fixed bug where if you added a new tag file, then moved that file in
    261. 

  261.     the list, a null exception occured during tagging.</li>
    262. 

  262.     <li>If tag collision popup is wider than the screen, place it flush to the
    263. 

  263.     left side of the screen</li>
    264. 

  264.     <li>Ability to have commas in tag index file path names</li>
    265. 

  265.   </ul>
    266. 

    267. 

  267. 	<li>Version 1.0, Initial public release (Oct 2001)</li>
    268. 

  268.   <ul>
    269. 

  269.     <li>Made Enter Tag dialog a stand alone dialog (no JOptionPane).</li>
    270. 

  270.     <li>Moved enter event into KeyPressed() in enter tag dialog.</li>
    271. 

  271.     <li>Added the display of exuberant info from the tag indx file.</li>
    272. 

  272.     <li>Reverted back to platform independent Monospaced font for tag collision list.</li>
    273. 

  273.   </ul>
    274. 

    275. 

  275. 	<li>Version 0.9.2 (Oct 2001)</li>
    276. 

  276.   <ul>
    277. 

  277.     <li>Listen for ENTER in Enter Tag dialog.</li>
    278. 

  278.     <li>Use KeyEventWorkaround.processKeyEvent() in key listener.</li>      
    279. 

  279.     <li>Removed display of wait cursor when opening tag definition file.</li>
    280. 

  280.   </ul>
    281. 

    282. 

  282. 	<li>Version 0.9.1 (Oct 2001)</li>
    283. 

  283.   <ul>
    284. 

  284.     <li>Removed Tags.displayMessage in favor of org.gjt.sp.util.Log.log()</li>   
    285. 

  285.     <li>Used ^ and $ from tag index file when searching (regexp)</li> 
    286. 

  286.     <li>Fixed bug where search string wasn't complete</li> 
    287. 

  287.     <li>Fixed off by 1 bug when tag index file uses line numbers</li> 
    288. 

  288.   </ul>
    289. 

    290. 

  290. 	<li>Version 0.9 (Oct 2001)</li>
    291. 

  291.   <ul>
    292. 

  292.     <li>Scroll pane for collision dialog.</li>
    293. 

  293.     <li>Added public Tags.pushPosition()</li>
    294. 

  294.     <li>Better display tag information collision list.</li>
    295. 

  295.     <li>Fixed bugs introduced in 0.7.3.</li>
    296. 

  296.     <li>Display tag line numbers in collision list when search string is a line
    297. 

  297.     number.</li>
    298. 

  298.     <li>Changed font of collision list from "Monospaced" to "Courier New".</li>
    299. 

  299.     <li>Removed public use of tag catagories.</li>
    300. 

  300.     <li>Fixed Enter Tag dialog focus issue.</li>
    301. 

  301.     <li>Only display 1 - 9 in collision list.</li>
    302. 

  302.     <li>Resolve relative tag defintion files before possible use of tag collision 
    303. 

  303.     list.</li>
    304. 

  304.   </ul>
    305. 

    306. 

  306. 	<li>Version 0.7.3 (Oct 2001)</li>
    307. 

  307.   <ul>
    308. 

  308.     <li>Ability to use number keys with the tag collision popup.</li>
    309. 

  309.     <li>Fixed relative tag defintion file name path problem.</li>
    310. 

  310.     <li>Fixed problem when tagging from command line.</li>
    311. 

  311.     <li>Fixed infinite loop problem when backtracking to beginning of first 
    312. 

  312.     line in tag index file.</li>
    313. 

  313. 	  <li>Fixed crash when tag is on last line of tag index file.</li>  
    314. 

  314.     <li>Made Java 1.1 compatible</li>
    315. 

  315. 	</ul>
    316. 

    317. 

  317. 	<li>Version 0.7.2 (Oct 2001)</li>
    318. 

  318.   <ul>
    319. 

  319.     <li>Added the ability to specify the tag index file name, when using the
    320. 

  320.     tag index file in the current buffer's directory.</li>
    321. 

  321.     <li>Added error message when tag defintion file does not exist</li>
    322. 

  322. 	  <li>Updated HTML Documentaiton.</li>    
    323. 

  323. 	</ul>
    324. 

    325. 

  325. 	<li>Version 0.7.1 (Oct 2001)</li>
    326. 

  326.   <ul>
    327. 

  327. 	  <li>Updated HTML Documentaiton.</li>
    328. 

  328. 	  <li>Updated labels and property strings.</li>
    329. 

  329.     <li>Let user know if no tag index files have been specified.</li>
    330. 

  330.     <li>Removed tag index file type specification.</li>
    331. 

  331.     <li>Removed some unneeded code.</li>
    332. 

  332. 	</ul>
    333. 

    334. 

  334. 	<li>Version 0.7 (Oct 2001)</li>
    335. 

  335.   <ul>
    336. 

  336. 	  <li>HTML Documentaiton</li>
    337. 

  337. 	  <li>Use AbstractOptionPane for Global Options dialog</li>
    338. 

  338. 	</ul>
    339. 

  339.   
    340. 

  340. 	<li>Version 0.5 (Oct 2001)</li>
    341. 

  341.   <ul>
    342. 

  342. 	  <li>??</li>
    343. 

  343. 	</ul>
    344. 

  344.   
    345. 

  345.   <li>Version 0.3 (Sep 2001)</li>
    346. 

  346.   <ul>
    347. 

  347. 	  <li>Initial beta release</li>
    348. 

  348.   </ul>
    349. 

  349. </ul>
    350. 

    351. 

  351. </body>
    352. 

  352. </html>
    353.