#
# Copyright (c) 2015
#	Tama Communications Corporation
#
# This file is part of GNU GLOBAL.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
# 
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
# 
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.
#
@HEADER	GTAGS.CONF,5,Nov 2015,GNU Project
@NAME	gtags.conf - configuration data for GNU Global
@SYNOPSIS
	@file{gtags.conf}
	@file{~/.globalrc}
@DESCRIPTION
	@file{gtags.conf} has configuration data for @xref{global,1}, @xref{gozilla,1},
	@xref{gtags,1} and @xref{htags,1}. They look for the following files in this order,
	and read from the first one that exists and is readable.
	@begin_itemize
	@item{(1) --gtagsconf @arg{file}}
	@item{(2) $GTAGSCONF}
	@item{(3) [project root]/gtags.conf}
	@item{(4) [project root]/[objdir]/gtags.conf}
	@item{(5) $HOME/.globalrc}
	@item{(6) /etc/gtags.conf}
	@item{(7) [sysconfdir]/gtags.conf}
	@end_itemize

	[sysconfdir] is @file{/usr/local/etc} by default; you can change it by the --sysconfdir
	option of the configure script. [objdir] is @file{obj} by default; you can change it
	by @var{GTAGSOBJDIR} or @var{MAKEOBJDIR}.

	Its syntax is similar to @xref{termcap,5} except for some extensions described later.
	A file includes one or more records. You should select a record using a label.
	Default label is @samp{default}. If @var{GTAGSLABEL} is set, its value is used.
	Please be aware the meaning of @samp{default} is different from that of @xref{termcap,5}.

	Lines starting with @samp{#} are ignored.
	A record consists of one or more fields separated by @samp{:} and ends with a newline.
	The first field must have a label name. Each field of the rest has a variable definition.
	There are three types in those variables.
	@begin_itemize
	@item{Boolean: This type has no value; existence of variable means true else false.}
	@item{Number: This type has a number value after @samp{#}.}
	@item{String: This type has a string value after @samp{=}.}
	@end_itemize
	Most variables are relevant to string type.

	If data includes @samp{:} or newline, you need to quote it by @samp{\}.
	An empty field is permitted, but it doesn't make sense.

	When there is more than one definition, the previous one is adopted. 
	Exceptionally, all values of @name{skip}, @name{langmap} and @name{gtags_parser} are
	adopted and connected respectively.
@Variable substitution
	Variable substitution similar to @xref{sh,1} is available.
	You can refer to any string variable using @samp{$} prefix. For example, the following
	@name{b} has a value @samp{XYZ}.
	@begin_verbatim
	:a=Y:b=X${a}Z:
	@end_verbatim
@Including another record
	@name{Tc} is a special variable; it reads in definitions in another record.
	It is similar to the @name{tc} of @xref{termcap,5}.
	Its syntax is as follows:@br
	@name{tc}=@arg{label}[@@@arg{file}]@br
	If only a @arg{label} is given, @name{tc} is read from a record specified by the @arg{label}
	in the same file. If @@@arg{file} is also given, @name{tc} is read from a record
	specified by the @arg{label} in the specified @arg{file}.
	@arg{File} should be an absolute path, and should not include variables.
	Different from @xref{termcap,5}, you can use @name{tc} anytime anywhere.
@CONFIGURATION
	About variables for each command, please see each manual.

	You can use the following environment variables as a string variable.
	If these variables are set then environment variables of the same name are set before
	command execution.@br
	@name{GREP_COLOR}@br
	@name{GREP_COLORS}@br
	@name{GTAGSBLANKENCODE}@br
	@name{GTAGSCACHE}@br
	@name{GTAGSFORCECPP}@br
	@name{GTAGSGLOBAL}@br
	@name{GTAGSGTAGS}@br
	@name{GTAGSLIBPATH}@br
	@name{GTAGSLOGGING}@br
	@name{GTAGSTHROUGH}@br
	@name{GTAGS_OPTIONS}@br
	@name{HTAGS_OPTIONS}@br
	@name{MAKEOBJDIR}@br
	@name{MAKEOBJDIRPREFIX}@br
	@name{TMPDIR}@br

	The following variables are also available as a string variable.
	By default, each of them has a directory path given by the configure
	script.@br
	@name{bindir}@br
	@name{datadir}@br
	@name{libdir}@br
	@name{localstatedir}@br
	@name{sysconfdir}@br
@ENVIRONMENT
	The following environment variables affect the execution of the commands.

	@begin_itemize
	@item{@var{GTAGSCONF}}
		If this variable is set, the value is used as a configuration file.
	@item{@var{GTAGSLABEL}}
		If this variable is set, the value is used as a label of the configuration file.
		The default is @arg{default}.
	@end_itemize
@SEE ALSO
	@xref{global,1},
	@xref{gozilla,1},
	@xref{gtags,1},
	@xref{htags,1}.

	GNU Global source code tag system@br
	(http://www.gnu.org/software/global/).
@HISTORY
	The @name{gtags.conf} file appeared in Global-3.0 (1998).
