ExTAGS 3.01 - April 29, 1991

This is a *FREE* macro+executable for Brief users.
Actually a two part feature:

1)	a Brief macro to add the much-required "go to tag" feature. This
	one can be easily modified to use any tags program such as ctags
	or etags (which can be found in the IBM Programming Forum).

2)	a sophisticated ctags-like utility for Microsot languages and
	compatibles (such as Glockenspiel C++) to exploit the use of tags.

1) Extags - the Brief macro

	To use extags you just need to take the macro code (extags.cb) and
	compile it ("cb extags"). You will also need to compile
	inflib.cb which contains useful functions and is used by
	extags.
	Be sure to put your .cm files in the BPATH directory.
	Then modify your initial macro as follows:
	E.g. (from user.m, initial macro of "user").


	;**	Initials macro.
	;**	Use this macro for additional customization.
	(macro user
		(
		;**	Put your changes here.
			(load_macro "extags")
			(return)
		)
	)	   	

	You need to "load_macro" extags because it registers as <Alt-]> on
	startup. You can modify the macro to change assignment.
	Recompile the macro ("cm user").
	Brief will automatically load ExTAGS on startup.
	
	ExTAGS uses a customized tags file. This implementation uses
	a file formatted this way: (fields separated by blank or tabs)

	<tags type> <symbol type> <symbol name> <file name> <line number>

	<tags type> can be:
		c		constant
		f		function
		m		macro
		t		user-defined type
		v		variable
		p		parameter
		R		reference

	<symbol type> can be:
		P		public
		S		static
		L		local

	<symbol name> is the tag name

	<file name> is the file name where you can find the definition
		    of <symbol name> (full path admitted)

	<line number> is the line number, in the file, where the definition
		    is found.

	E.g.:
		v	S 	static_var  foo.c 45

	means the definition on the variable "static_var", static, can be
	found in the file foo.c, at line 45.
	The R type is always associated to a P class (since it really
	doesn't matter what class it is!).

	ExTAGS interprets and reads these info to create a menu.
	When activated with <Alt-]> (or whatever is defined to be
	the key) show a menu, loads the file, and positions the user
	on the definition of the indicated symbol. You can the use
	<Ctrl-6><Ctrl-6> ("extags_switch") to switch back to the
	original buffer.

	The file where ExTAGS looks for information is, by default,
	"tags.tgs", in the current directory. You can modify the location
	by using an environment variable, BTAGS.

	E.g.:
		set BTAGS=h:\c\mysource\mytags

	means ExTAGS will try to load the file mytags in h:\c\mysource.

	ExTAGS loads the needed info the first time a particular feature
	is called ('Functions', 'Types', 'Constants', 'Variables' or
	'References'). Since this can dramatically reduce the available memory
	(info is kept in system buffers) buffers can be purged from memory
	with a single command in the main menu.
	'Reinit' purges all buffers and reloads the functions-related info.
	'Purge buffers' purges all buffers.
	'Purge references' purges only the references buffer (the biggest one
	in every case).

	References are not used on a menu basis. You just position the cursor
	on a symbol name and press the keys associated with "extags_ref"
	(<Ctrl-6><Ctrl-2> by default). ExTAGS cycles among references to
	the symbol.

	The reference feature can work in two modes. SLOW mode (the default)
	loads only the info associated to the current symbol. When you
	change symbol, info is reloaded. Thus info is loaded only once per
	"tour" on the same symbol but doesn't waste up memory.
	FAST mode loads info once-for-all like all others features. You must
	explicitly unload it with 'Reinit', 'Purge buffers' or 'Purge
	references' (the last one being specific for THIS kind of info). 
	FAST mode is activated by calling extags_ref with a non-zero parameter.
	You can easily set this adding the following line to your initials
	macro, AFTER the line in which you load ExTAGS:
		(assign_to_key "<Ctrl-6><Ctrl-2>" "extags_ref 1")

	


2) ExTAGS - the Microsoft Languages Browser Database translator
	
	You can use other "tags" programs provided you accordingly
	modify extags.cb (the Brief macro).

	But ExTAGS (extags.exe) is a ready-to-use companion "tags" program
	to use with Microsoft Languages and others capable to produce
	a "Browser database" such as you can find in Microsoft C 6.0.
	For example, Glockenspiel C++ is able to produce such a file
	by cooperating with the Microsoft C 6.0 compiler. 
	ExTAGS is NOT depending on a particular configuration.

	When the "Browser database" is produced, you run extags like this:

			extags browser.bsc

	produces a file named "tags.tgs" with the translation of the
	"Browser database" in ExTAGS format (see point 1.).

	The complete syntax (you can have it anytime by calling
	extags without arguments) is:

		extags [-[q][f][o <tags file>]] <browser-db> ...
	
	q means extags won't produce output (useful for batch mode)
	  ExTAGS returns the errorlevel this way:

		-1 if a DOS error is encountered during execution
		   (means low memory, or temporary file problems,
		   or impossibility to open the database...)
		1  if the syntax was wrong
		0  if processing completed successfully.

	f means extags will produce (if possible) the full name
	  of the code file (field <file name>) in the tags.tgs file.

	o followed by a valid file name means ExTAGS will direct
	  output to that file instead of "tags.tgs" (the default).

	If a filename in the <browser-db> list begins with '@',
	it is interpreted as a list-file and ExTAGS will scan it
	and process every file listed in it. The list should be
	(you guess!) one filename per line.

	ExTAGS is now limited to 64K of output file because it uses
	the DOS sort utility in the final phase.
	Should any interest manifest, we will upgrade the program
	with a built-in sort.

	The following direction will help Microsoft C users:

	a) the browser database is produced by pwbrmake.
	   when compiling, use -Fr<file name>.sbr. This will
	   give you a <file name>.sbr partial database.

	b) then execute
		pwbrmake -Es -n -o <bsc-database> <sbr-files...>

	   This will produce <bsc-database>.bsc with which you
	   can directly feed ExTAGS with
		extags <bsc-database>.bsc

	   and have a tags.tgs file.

	
	The following directions will help Glockenspiel C++ users:

	a) the browser database is produced by pwbrmake.
	   when compiling, use -MW !d !v -c -Fr<file name>.sbr.
	   This will give you a <file name>.sbr partial database.

	b) then execute
		pwbrmake -Es -n -o <bsc-database> <sbr-files...>

	   This will produce <bsc-database>.bsc with which you
	   can directly feed ExTAGS with
		extags <bsc-database>.bsc

	   and have a tags.tgs file.

	The general use is: with debugging on you get much more info.

	
	The following "TOOLS.INI" rules will help Microsoft Languages
	users (add this to the [NMAKE] section or create one):

	[NMAKE]
	.SUFFIXES: .sbr .bsc .cxx

	.obj.sbr:
		cl -Zs -Zi -Fr$@ $*.c

	.sbr.bsc:
		pwbrmake -Es -n -o $@ $**

	.bsc.tgs:
		extags -o $@ $**

	.cxx.sbr:
		ccxx -MW !d !v -c -Fr$@ $*.cxx

	With these rules, you can easily build the makefile to look like
	this:

	OBJS=foo.obj fake.obj
	SBRS=foo.sbr fake.sbr

	foo.obj: foo.c
		cl ... -c -Frfoo.sbr foo.c

	fake.obj: fake.c
		cl ... -c -Frfake.sbr fake.c

	fake.exe: $(OBJS)
		<link command line>

	fake.bsc: $(SBRS)		# the tools.ini rule does the rest

	tags.tgs: fake.bsc		# the tools.ini rule does the rest

	fake: fake.exe fake.bsc


	and the build everything using "nmake fake".



Even though we have been using this for some time now, don't
be upset if it malfunctions!
Let us know if any problem shows up, or if you're interested in extensions.
We will try to catch up if we can use another compiler or have sufficient
informations on tags or debugging informations.
The source code of ExTAGS.exe is not included only because you must
have the Microsoft Developer's Toolkit with the browser database library,
and a custom module to process command-line options (derived from
an article in the C Users Journal, Vol. 8 #7 (July 1990) -
"An Objected-Oriented Approach to Command Line Options", by Don Colner).

You can contact us at CompuServe ID 100016,2335. Nick names Shari and
Lrkwz.

Shari (Davide Migliavacca)
Lrkwz (Luca Orlandi)
Inferentia S.r.l.
v. Venezian, 10
Milano ITALY
tel. +39.2.26680568
CompuServe: 100016,2335 (Alberto Fioravanti)
		

Inferentia S.r.l. is an italian consulting firm, specialized in 
Windows, OS/2, C++ (italian distributors of Glockenspiel C++), 
GUIs (Glockenspiel CommonView, 	CaseWorks CASE:W and CASE:PM) and
Windows applications (Dynacomm, ObjectScript, ObjectView...)

Milan, April 1991
	
	

	
	
	


	



		
