This is a design memo about supporting new tag for less.

-----------------
Important matters
-----------------

o The new less should be completely upper compatible.
o We should not waste options for new facilities because it is precious
  and, in fact, it is little leaved.:-)
o GLOBAL and recent ctags support duplicate tags. So new less should be
  able to treat duplicate tag.
o GLOBAL has some tag files, that is:
        'GTAGS'         function definitions
        'GRTAGS'        function references
        'GSYMS'         other symbols
        'GPATH'         path names
  So, new less should be able to select one of them.
o GLOBAL can use external search engine like grep(1) and id-utils(1).
  New less should be general enough to treat theses advanced facilities.

--------------
Specifications
--------------

o Support multi tag

  New less supports following tag files:
	Traditional tags by ctags.
	Extended tags by Exuberant Ctags <http://ctags.sourceforge.net>
	GLOBAL's tag by global.
	Ctags -x format from stdin.

  User can specify tag file by the -T option.

	% less -t main			-- tag file is 'tags' (default)

	% less -TGTAGS -t main		-- use GTAGS

	% ctags -x *.c | less -T-	-- use ctags -x format from stdin

  About GLOBAL's tag, GTAGS, GRTAGS, GSYMS and GPATH are available as tag
  file name. User must not specify the path(GLOBAL locate the path).

  About ctags -x format, both of standard and extended format are supported.

	[standard format]
	<tag>   <lineno>  <file>         <image>
	+------------------------------------------------
	|main     30      main.c         main(argc, argv)
	|func     21      subr.c         func(arg)

	The following commands write this format.
	   o Traditinal Ctags with -x option
	   o Global with -x option

	[extended format]
	<tag>   <type>  <lineno>   <file>        <image>
	+----------------------------------------------------------
	|main     function 30      main.c         main(argc, argv)
	|func     function 21      subr.c         func(arg)

	Exuberant Ctags with -x option write this format.
	See <http://ctags.sourceforge.net>

  Following usages are available with this facility.

        % global -xg 'lseek(.*)' | less -T-	# grep(1) needed.
        % global -xI func | less -T-		# id-utils(1) needed.
        % ctags -x func | less -T-


o Support duplicated tag

  News less also supports duplicated tag entries.
  This facility is supported in all tag files. In traditional tag file,
  it is treated special case that tag is only one.

  At first, less shows the first tag. User can move to the next or previous
  entry by 't'(next) and 'T'(previous) command.

        't'             go to the next entry
        'T'             go to the previous entry

o Rare case spec

  If user invoke examin command while tag structure loaded,
  less cleanup tag structure leaving ifile structure.

	(1)
	% less -t main
	...
	[lessecho.c (tag 1 of 4)]	<- 4 tags found.
					   currently lessecho.c loaded.

	(2)
	Examine: edit.c			<- examine 'edit.c'

	(3)
	...
	[edit.c (file 2 of 2)]		<- insert edit.c in ifile structure.

	(4)
	t				<- go to next tag
	[No next tag  (press RETURN)]	<- no tag structure

  If user use stdin as tag file (by -T- option) and invoke ':t' command
  in less then less use default tag file, that is, 'tags'.


---------
ChangeLog
---------

o Two command added.

	[cmd.h, decode.c, command.c]
	't'	A_NEXT_TAG	go to next tag
	'T'	A_PREV_TAG	go to previous tag

o Some global variables were moved to tag entry.

	[tags.c]
	tagfile
	taglinenum
	tagpattern
	tagendline
	   |
	   v
	struct tag {
	      CIRCLEQ_ENTRY(tag) ptrs;
	      char *tagfile;          /* source file containing the tag */
	      int taglinenum;         /* appropriate line number of source 
	      char *tagpattern;       /* pattern which should be used to f
	      char tagendline;        /* 1: the pattern include '$' */
	};

o Use CIRCULAR macro in BSD queue for in memory tag structure.

	[tags.c]
	#include <queue.h>

	(header)	     curtag(current)
	tag_q                v
	+-------+<--+----+<--+----+<--+----+<---+
	|first *--->|   *--->|   *--->|    |--+ |
	|       |   +----+   +----+   +----+  | |
	|last  *--------------------------------+
	+-------+<----------------------------+

o Some modification about %macro in prompt.

	[prompt.c]
	%T macro added. %T means 'tag' if tag structure is loaded
	else 'file'.

	%i macro means sequence number of tag when tag structure is loaded.

	%n macro is always true while tag structure is loaded.
