home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / FTAG11.ZIP / FTAG.DOC < prev    next >
Text File  |  1991-01-09  |  14KB  |  336 lines
  1.  
  2.                       FTAG by Joe Kleinwaechter
  3.                       _________________________
  4.  
  5.                               v1.1
  6.  
  7.  
  8.  
  9. Contents
  10. ________
  11.  
  12. This small two file set is an add-on utility to the Brief text editor
  13. that allows file tagging using Microsoft C 6.0's Browser database.
  14. Included in this upload should be the following files:
  15.     1) ftag.doc - This file
  16.     2) ftag.exe - DOS version of ftag.exe
  17.     3) ftag.cm  - DOS version of ftag.cm
  18.     4) ftag.exo - OS/2 version of ftag.exe
  19.     5) ftag.cmo - OS/2 version of ftag.cm
  20.  
  21. If you are using DOS, you should delete FTAG.EXO and FTAG.CMO. If you
  22. are using OS/2 you should delete FTAG.EXE and FTAG.CM, rename
  23. FTAG.EXO to FTAG.EXE, and rename FTAG.CMO to FTAG.CM. Whichever
  24. version you are using, when you are done there should only be three
  25. files remaining, FTAG.DOC, FTAG.EXE and FTAG.CM.
  26.  
  27. History
  28. _______
  29.  
  30. v1.0 - Initial release includes tagging of definitions only
  31. v1.1 - Added tagging of references.
  32.        Added goto next mechanism.
  33.        OS/2 support.
  34.  
  35. What is ftag?
  36. _____________
  37.  
  38. FTAG is a specific implementation of the file tagging process
  39. commonly known as CTAGS in the Unix world. Simply stated, this allows
  40. one to edit a C source file, place the cursor over a symbol (function
  41. or variable), press a key and be transferred to the file where that
  42. symbol is defined or referenced. This is often called a "hyper-link".
  43. This is an easy way to move around between several source modules
  44. without having to recall where a particular symbol is defined.
  45.  
  46. Why is FTAG different? With so many excellent CTAG interfaces around,
  47. why invent another one? FTAG is different because it links two of the
  48. most popular development tools around; the Brief text editor and the
  49. Microsoft 6.0 compiler. If you do not have both of these packages,
  50. this program will not be of use to you.
  51.  
  52. With the current release of the Microsoft C compiler (6.0), came a
  53. new utility called the Source Code Browser. This was a wonderful
  54. utility, however it was of no use to you unless you also used the
  55. Microsoft PWB editor (YUK!). Many of us Brief users wanted the
  56. Browser access badly, but not if it meant giving up Brief. Luckily,
  57. Microsoft has recently disclosed the details of the Browser (as well
  58. as other goodies) and released them to the public as the Developer's
  59. Toolkit Reference. 
  60.  
  61. This recent development prompted the release of the first of many
  62. FREEWARE products that I intend to release interfacing Brief to the
  63. Browser.
  64.  
  65. How do I use FTAG?
  66. __________________
  67.  
  68. Once installed (see "How do I install FTAG?", later), FTAG is quite
  69. simple. It is transparently hooked into the "GOTO" routine that
  70. already exists (Alt-G). Goto works just as it did before, except that
  71. a default value will be placed in the prompt. This value will be the
  72. symbol located either under the cursor or the one next to it. If you
  73. want to use GOTO as before simply type the line number as usual.
  74. However, if you want to go to where the default symbol shown is
  75. DEFINED, just type ENTER. You can also replace the default symbol
  76. with any valid symbol (case-sensitive) when prompted with "Goto ?".
  77. In summary:
  78.  
  79.     - If you want to use GOTO as usual (to goto a particular line
  80. number), simply type ALT-G and enter the line number followed by
  81. <CR>.
  82.  
  83.     - If you want to find the definition of a symbol (tag), place the
  84. cursor over the symbol to look for, type ALT-G and then press <CR>.
  85.  
  86.     - If the symbol you want to look for is not readily accessible,
  87. simply type ALT-G and enter the symbol name by hand followed by a
  88. <CR>.
  89.  
  90. After performing the search, the file where the symbol is DEFINED is
  91. placed on the screen with the cursor positioned at the start of the
  92. line where the symbol is located. Note that the Browser tags the
  93. start of a function as the first open brace "{" after the function
  94. name.
  95.  
  96. Sometimes a directory has several development projects going on at
  97. the same time. In this case, there could be more than one definition
  98. of the symbol. Since FTAG doesn't know which one you want, it will
  99. display a menu listing the choices. Simply place the cursor over the
  100. definition file desired and hit <CR>.
  101.  
  102. Now, with v1.1 and later you can perform the above operation to find
  103. not only where a symbol is defined but where it is referenced.
  104. Instead of using ALT-G, you use ALT-R (for reference). The reference
  105. feature works in the same manner as the definition feature.
  106.  
  107. Also, with v1.1 comes the ability to do repetitive searches with a
  108. single database access. As stated earlier, whenever multiple tags are
  109. found for a given symbol, a menu is displayed. Often one wishes to
  110. check out several of these locations. Rather than having to
  111. repetitively search the database, you can simply press the
  112. Keypad-Insert key (0). This will redisplay the last multiple tag menu
  113. (if one was defined) and place the cursor at the last tag that was
  114. selected.
  115.  
  116. How do I install FTAG?
  117. ______________________
  118.  
  119. Note: If you are upgrading FTAG from a previous version, see the
  120. section entitled "For those upgrading from v1.0". This will get you
  121. there quicker.
  122.  
  123. Installation is fairly straight forward. However, all steps must be
  124. completed.
  125.  
  126.     1) Copy the FTAG.EXE program into a directory that is identifed
  127.        in your PATH. 
  128.  
  129.     2) Define the environment string BSCFILE with the full location and
  130.        name of the Browser database (the .BSC file). This is done inside of
  131.        your AUTOEXEC.BAT file as follows:
  132.  
  133.        set BSCFILE=D:\PROJECT\DB.BSC
  134.  
  135.        Obviously, the right side of the equal sign is specific to your
  136.        directory structure and Browser database name.
  137.  
  138.     3) Place the file FTAG.CM into a directory identified by the
  139.        Brief environment string BPATH. This is where your Brief macros
  140.        reside.
  141.  
  142.     4) Edit your initials macro source file and add the following
  143.        line to your initals macro:
  144.  
  145.    autoload ("ftag.cm", "gotoTag", "gotoReference","nextTag");
  146.    assign_to_key("<Alt-g>", "gotoTag");
  147.    assign_to_key("<Alt-r>", "gotoReference");
  148.    assign_to_key ("<Keypad-Ins>", "nextTag");
  149.  
  150. NOTE: These statements assume the use of CBRIEF (Brief v3.0 and
  151. later). If you are using a version of Brief prior to this see the
  152. section entitled "For versions of Brief prior to v3.0".
  153.  
  154. Parts of the line are case-sensitive so to be safe, type it exactly
  155. as shown. The first line tells Brief that whenever a call is made to
  156. the macro gotoTag, load in the file ftag.cm (this is where gotoTag is
  157. located). The second line tells Brief to assign the macro gotoTag to
  158. the key ALT-G. This will override the current goto macro. This is ok,
  159. because the new macro incorporates all of the old features plus more.
  160.  
  161. That's it!
  162.  
  163.  
  164. How do I make a Browser database?
  165. _________________________________
  166.  
  167. There's a loaded question if I have ever seen one. Actually, this is
  168. covered indirectly in the Microsoft manuals. However for the sake of
  169. simplicity I will show you the way(s) that I have implemented the
  170. browser and let you go from there.
  171.  
  172. The final Browser database is one large file given the extension
  173. .BSC. For our purposes let's call it PROJ.BSC. Browser data is gained
  174. from the compiling of source code into object modules. If you want to
  175. eventually include symbols from a source module into a Browser
  176. database you must include the /FR switch on the compile line. For
  177. example, to compile a module called SRC1.C into an object module you
  178. would supply a line something like this:
  179.        
  180.        cl /FR /c src1.c
  181.  
  182. When the compiler builds this object module, it also builds a .SBR
  183. file having the same name. If a project had ten source files, it will
  184. then have ten .SBR files. The .BSC file is created using the
  185. information in the .SBR file. This is done using the PWBRMAKE utility
  186. provided with the C compiler. (Use Quickhelp to obtain the command
  187. line layout). I use the PWBRMAKE in incremental mode. This means that
  188. the .BSC file is simply refreshed when PWBRMAKE is called not
  189. re-created. If you are using a makefile (strongly recommded) you have
  190. a choice to make. You can either place the call to PWBRMAKE as a rule
  191. in your ".c.obj" inference or you can call it as the result of a
  192. separate target build, called BROWSER for example. If your database
  193. consists of many files I would recommend the latter. The first method
  194. guarantees that your database will be refreshed whenever you compile
  195. a file. This however can add significant time to a compile. By making
  196. a target called BROWSER, you can update the Browser database by
  197. simply calling MAKE with BROWSER as the target. This is less time
  198. consuming, but you are manually responsible refreshing the database.
  199. No matter which method is used, the following is the format for the
  200. PWBRMAKE call assuming PROJ.BSC is the database name and the
  201. database is updated incrementally:
  202.  
  203.         @pwbrmake /v /o PROJ.BSC *.sbr
  204.  
  205.  
  206. It is important to note that when a .SBR file is created, it has a
  207. size greater than zero. Once its contents have been used to refresh
  208. the .BSC file, its file size reduces to zero. Even though the file
  209. size is zero, YOU MUST NOT DELETE THIS FILE. It is used as a
  210. place-marker when PWBRMAKE is called to know what to maintain in the
  211. database.
  212.  
  213.        
  214. For versions of Brief prior to v3.0
  215. ____________________________________
  216.  
  217. All of the modifications shown to the Brief initials macro assume the
  218. new CBRIEF notation. If you are using a version prior to this
  219. translate the statements according to this table:
  220.  
  221. Translate:
  222.        autoload ("ftag.cm", "gotoTag", "gotoReference","nextTag");
  223.        assign_to_key("<Alt-g>", "gotoTag");
  224.         assign_to_key("<Alt-r>", "gotoReference");
  225.        assign_to_key ("<Keypad-Ins>", "nextTag");
  226.  
  227. To:
  228.        (autoload "ftag.cm" "gotoTag" "gotoReference" "nextTag")
  229.        (assign_to_key "<Alt-g>" "gotoTag")
  230.         (assign_to_key "<Alt-r>" "gotoReference")
  231.        (assign_to_key "<Keypad-Ins>" "nextTag")
  232.  
  233. For those upgrading from v1.0
  234. ______________________________
  235.  
  236. I am sorry that v1.1 has been released so close to the release of
  237. v1.0, but I felt the new features were significant enough to justify
  238. this. As it turns out, they were not as difficult as I had expected.
  239.  
  240. If you are currently using FTAG v1.0, simply do the following:
  241.     - Delete the old ftag.exe and replace it with the new one
  242.        included.
  243.  
  244.     - Delete the old FTAG.CM and replace it with the new one, also.
  245.  
  246.     - Modify:
  247.        autoload ("ftag.cm", "gotoTag");
  248.       to read:
  249.        autoload ("ftag.cm", "gotoTag", "gotoReference","nextTag");
  250.        
  251.     - Leave the following line as it is:
  252.        assign_to_key("<Alt-g>", "gotoTag");
  253.     
  254.     - Add the following two lines:
  255.         assign_to_key("<Alt-r>", "gotoReference");
  256.        assign_to_key ("<Keypad-Ins>", "nextTag");
  257.  
  258.  
  259. NOTE: These statements assume the use of CBRIEF (Brief v3.0 and
  260. later). If you are using a version of Brief prior to this see the
  261. section entitled "For versions of Brief prior to v3.0".
  262.  
  263.  
  264. You can, of course, use any keys you want. These are ones I happen to use.
  265. That's it. For a description of the new features see the following
  266. section.
  267.  
  268.  
  269. How can I improve its performance?
  270. __________________________________
  271.  
  272. If it seems to take an excessive amount of time to switch to the
  273. tagged file you may want to check how Brief is swapping. Under most
  274. circumstances you don't need to turn swapping on (see the -M switch
  275. in the Brief manuals). If swapping is enabled and tagging is taking a
  276. long time, try disabling it. If this significantly improves the time,
  277. it means that when you are swapping out Brief, it does not have enough
  278. EMS memory to swap to, therefore it is saving and restoring itself to
  279. disk. In my opinion, swapping to disk is not a viable option for most
  280. operations.
  281.  
  282.  
  283. Can I give this program to a friend?
  284. ____________________________________
  285.  
  286. YES! FTAG is distributed as a FREEWARE program. This means that
  287. anyone is free to use the program at NO CHARGE. The author assumes no
  288. liabilty in its use therefore the user is at his own risk. I retain
  289. the rights to FTAG and do not give anyone the permission to
  290. distribute this program for a fee. If you find that someone is
  291. charging for this program pleas contact me at the number below.
  292.  
  293. I have thoroughly tested this program on my machine (a Dataworld 386)
  294. and seem to have gotten all of the bugs out. It is currently in its
  295. first release, however, so some unexpected situations may occur. If
  296. you are having a problem with FTAG feel free to contact me at the
  297. number below.
  298.  
  299.  
  300. Will there be anymore Brief/Browser programs coming?
  301. ____________________________________________________
  302.  
  303. Yes. I am currently working on developing a more comprehensive
  304. Browser access machine to allow calltrees and file characterization.
  305. I am not sure when they will be released (FREEWARE of course), but if
  306. you have any ideas of how you would like to see a product like this
  307. operate feel free to contact me at the number below.
  308.  
  309.  
  310. Kudos
  311. _____
  312.  
  313. Special thanks to Bruce Mallet of M-Tek (Derry, N.H.) for his
  314. wonderful Brief macros package called ELEC-C. I highly recommend
  315. obtaining a copy of this program (call the Brief BBS). While I did
  316. not use his code directly, I did steal (with his permission) his
  317. method of hooking the tag system into the Alt-G and the idea of using
  318. the Dialog Manager when multiple definitions occur. Note that FTAG
  319. complements ELEC-C well. There are some minor mods necessary to
  320. disable his tag routines, but I will be happy to supply them to
  321. anyone wishing to do so.
  322.  
  323. Contact
  324. -------
  325.  
  326. I will be happy to communicate to anyone using a number of different
  327. methods. By BBS you can reach me (KLEINW) at:
  328.  
  329.        (404)320=6202      (AV-Sync)
  330.        (404)378-7914      (Shareware South)
  331.  
  332. or I can be reached via Internet at:
  333.  
  334.        kleinw@swamc1.sinet.slb.com
  335.  
  336.