___________________________________
|      |  |  |     |  _  |     |  |
|  |___|  |  |  |  |    _|  |  |  |    GNU GLOBAL source code tag system
|  |   |  |  |  |  |     |     |  |
|  ~~  |   ~~|     |  ~  |  |  |   ~~|          for all hackers.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Copyright (c) 2011, 2013, 2014 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 parser. It has three 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.
Pygments + Exuberant Ctags('pygments-parser.c')
	A parser to use Pygments and Exuberant Ctags.

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

You should write a parser function in 'plugin-factory/user-custom.c'
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: 
o Gtags always makes 'GRTAGS' file even if you don't use PARSER_REF_SYM.
o You can write a plug-in parser independently with GLOBAL except for 'parser.h'.
  Plug-in factory is supplied only for your convenience.

[build and install]

$ cd plugin-factory
$ make
$ sudo make install


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
