___________________________________
|      |  |  |     |  _  |     |  |
|  |___|  |  |  |  |    _|  |  |  |    GNU GLOBAL source code tag system
|  |   |  |  |  |  |     |     |  |
|  ~~  |   ~~|     |  ~  |  |  |   ~~|          for all hackers.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Copyright (c) 2011, 2013 Tama Communications Corporation

 This file is free software; as a special exception the author gives
 unlimited permission to copy and/or distribute it, with or without
 modifications, as long as this notice is preserved.

 This program is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
 implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

                ----------------------------------

Plugin-factory directory ('plugin-factory/' in the GLOBAL package) is a factory
of plug-in parsers. It has two plug-in parsers which are installed into the
system by default.

Nop parser('user-custom.c')
	A skeleton parser. Nothing has been implemented yet.
Exuberant Ctags('exuberant-ctags.c')
	A parser to use Exuberant Ctags.

How to write a plug-in parser?
==============================

You should write a parser function in the nop parser like follows (pseudo code):

#include "parser.h"
void
parser(const struct parser_param *param)
{
	open param->file
	while (read from file) {
		if (definition)
			param->put(PARSER_DEF, ...);
		else if (reference)
			param->put(PARSER_REF_SYM, ...);
		else
			...
	}
	close file
}

A param argument is given to each parser function.
param->file is the path name of a source file which should be parsed.

You can write a tag using the param argument like follows:

o write a tag to GTAGS

	param->put(PARSER_DEF, <tag name>, <line no>, <file name>, <line image>, param->arg);

o write a tag to GRTAGS

	param->put(PARSER_REF_SYM, <tag name>, <line no>, <file name>, <line image>, param->arg);

Note: 
Gtags always makes GRTAGS even if you don't use PARSER_REF_SYM.

How to use Exuberant Ctags as a parser?
=======================================

'exuberant-ctags.la' is a shared library to use Exuberant Ctags,
and is installed to /usr/local/lib/gtags by default.

To use this parser, please do like follows:

        [Installation of GLOBAL]

        It assumed that ctags command is installed in '/usr/local/bin'.

        $ ./configure --with-exuberant-ctags=/usr/local/bin/ctags
        $ make
        $ sudo make install

        [Executing of gtags]

        It assumed that GLOBAL is installed in '/usr/local' which is the default.

        $ export GTAGSCONF=/usr/local/share/gtags/gtags.conf
        $ export GTAGSLABEL=ctags
        $ gtags                         # invokes Exuberant Ctags internally
