.\" This file is generated automatically by convert.pl from htags/manual.in.
.TH HTAGS 1 "March 2008" "GNU Project"
.SH NAME
htags \- generate hypertext from source code.
.SH SYNOPSIS
\fBhtags\fP [-acCDfFghInosTvwx][-d \fIdbpath\fP][-m \fIname\fP][-S \fIcgidir\fP][-t \fItitle\fP][\fIdir\fP]
.br
.SH DESCRIPTION
\fBHtags\fP makes hypertext of C, C++, Yacc, Java, PHP and Assembly source code.
.PP
In advance of using this command, you must execute
\fBgtags\fP(1) from the root directory of the source tree.
Then you can execute \fBhtags\fP from the same place.
\fBHtags\fP makes an directory named \'HTML\' and generates
hypertext in it.
You can start browsing from \'HTML/index.html\'.
.PP
Since \fBhtags\fP generates static hypertext as long as
the \fB-D\fP or \fB-f\fP option is not specified,
you can move it anywhere and browse it by any browser without
web server.
.PP
You must use same parser for both \fBgtags\fP(1) and \fBhtags\fP.
If you use the default parser, it is not necessary to consider for it.
.PP
.SH OPTIONS
If you are new on htags, it is recommended to invoke with the \fB--suggest\fP option.
With the option, \fBhtags\fP use popular options instead of you.
.br
The following options are available:
.TP
\fB-a\fP, \fB--alphabet\fP
Make an alphabetical function index which is suitable
for a large project.
.TP
\fB--caution\fP
Include caution message to prohibit downloading.
.TP
\fB-c\fP, \fB--compact\fP
Compress html files by \fBgzip\fP(1).
You need to set up a web server so that \fBgzip\fP(1)
is invoked for each compressed file.
See \'HTML/.htaccess\' that is generated by htags.
.TP
\fB-C\fP
Make compressed html files with a \fIhtml.gz\fP suffix.
Debian systems can usually uncompress these transparently
without the need for a CGI helper.
.TP
\fB--cvsweb\fP \fIurl\fP
Include cvsweb URL. \fIurl\fP is used as base of URL.
When directory \'CVS\' exists in the root directory of source project,
the content of \'CVS/Repository\' is used as the relative path from the base.
.TP
\fB--cvsweb-cvsroot\fP \fIcvsroot\fP
Specifies cvsroot in cvsweb URL.
.TP
\fB-D\fP, \fB--dynamic\fP
Generate object lists dynamically using CGI program.
By default, object lists are generated statically.
Though this option decrease both the size and the generation
time of the hypertext, you need to set up a web server, and
you cannot move the hypertext from the source directory.
.TP
\fB-d\fP, \fB--dbpath\fP \fIdbpath\fP
Specifies the directory in which \'GTAGS\' and \'GRTAGS\'
exist. The default is the current directory.
.TP
\fB--disable-grep\fP
Disable grep in the search form(-f,--form).
.TP
\fB-F\fP, \fB--frame\fP
Use frame for each part of the contents.
.TP
\fB-f\fP, \fB--form\fP
Support search form using CGI program.
You need to set up a web server, and you cannot move
the hypertext from the source directory.
.TP
\fB--full-path\fP
List file names with full path in the file index.
By default, list just the last component of a path.
.TP
\fB-g\fP, \fB--gtags\fP
Execute \fBgtags\fP(1) before creating hypertext.
The \fB-v\fP, \fB-w\fP and \fIdbpath\fP are passed to \fBgtags\fP.
.TP
\fB--gtagsconf\fP \fIfile\fP
Load user's configuration from \fIfile\fP.
.TP
\fB--gtagslabel\fP \fIlabel\fP
\fIlabel\fP is used for the label of configuration file.
The default is default.
.TP
\fB-h\fP, \fB--func-header\fP[=\fIposition\fP]
Insert function header for each function.
By default, \fBhtags\fP doesn't generates it.
You can specify the position using \fIposition\fP argument,
which allows one of before, right and after.
The default position is after.
.TP
\fB-I\fP, \fB--icon\fP
Use icons instead of text for some links.
.TP
\fB--insert-footer\fP \fIfile\fP
Insert custom footer derived from \fIfile\fP before
tag.
.TP
\fB--item-order\fP \fIspec\fP
Specify order of items in the top page.
The \fIspec\fP is a string consists of item signs in order.
Each sign means as follows:
\fBc\fP: caution, \fBs\fP: search form,
\fBm\fP: mains, \fBd\fP: definition, \fBf\fP: files.
The default is \fIcsmdf\fP.
.TP
\fB-m\fP, \fB--main-func\fP \fIname\fP
Specify the main function name. The default is main.
.TP
\fB-n\fP, \fB--line-number\fP[=\fIcolumns\fP]
Print line numbers. By default, doesn't print line numbers.
The default value of \fIcolumns\fP is 4.
.TP
\fB--no-map-file\fP
Doesn't generate \'MAP\' and \'FILEMAP\' file.
By default, \fBhtags\fP generates them.
.TP
\fB-o\fP, \fB--other\fP
Pick up not only source files but also other files except for
binary files.
.TP
\fB-S\fP, \fB--secure-cgi\fP \fIcgidir\fP
Write CGI programs into the \fIcgidir\fP to realize
a centralised CGI program.
Script alias is \'/cgi-bin\' by default.
You can overwrite this value using config variable
script_alias in \'gtags.conf\'.
.TP
\fB-s\fP, \fB--symbol\fP
Make anchors not only for object definitions and references but also other symbols.
.TP
\fB--statistics\fP
Print statistics information.
.TP
\fB--suggest\fP
\fBHtags\fP selects popular options instead of beginners.
It is equivalent to '-afghInosTxv --show-position' now.
.TP
\fB-T\fP, \fB--table-flist\fP[=\fIfields\fP]
Generate file list using tag.
The \fIfields\fP is used for field number in a line. The default is 5.
.TP
\fB-t\fP, \fB--title\fP \fItitle\fP
The \fItitle\fP of this hypertext. The default is the last
component of the current directory.
.TP
\fB--table-list\fP
List tags using tag.
.TP
\fB--tabs \fInumber\fP\fP
Tab stop. The default is 8.
.TP
\fB-v\fP, \fB--verbose\fP
Verbose mode.
.TP
\fB-w\fP, \fB--warning\fP
Print warning messages.
.TP
\fB-x\fP, \fB--xhtml\fP[=\fIversion\fP]
Generate XHTML hypertext instead of HTML.
If the \fB--frame\fP option is specified then
generate XHTML-1.0 Frameset for index.html
and generate XHTML-1.0 Transitional for other files,
else if \fIversion\fP is 1\.1 or config variable
xhtml_version is set to 1\.1 then generate
XHTML-1.1 else XHTML 1.0 Transitional.
.TP
\fIdir\fP
The directory in which hypertext is generated.
The default is the current directory.
.SH EXAMPLES
.nf
$ gtags -v
$ htags -sanohITvt 'Welcome to XXX source tour!'
$ firefox HTML/index.html
.PP
$ htags --suggest
.PP
.fi
.SH FILES
.TP
\'GTAGS\'
Tag file for object definitions.
.TP
\'GRTAGS\'
Tag file for object references.
.TP
\'GSYMS\'
Tag file for other symbols.
.TP
\'GPATH\'
Tag file for path of source files.
.TP
\'/etc/gtags.conf\', \'$HOME/.globalrc\'
Configuration file.
.TP
\'HTML/index.html\'
Index file for hypertext.
.TP
\'HTML/MAP\'
Mapping file for converting tag into path of hypertext.
External systems can utilize this file.
.TP
\'HTML/FILEMAP\'
Mapping file for converting file name into path of hypertext.
External systems can utilize this file.
.TP
\'HTML/style.css\'
Style sheet file. This file is generated when the \fB--xhtml\fP
option is specified.
.SH ENVIRONMENT
The following environment variables affect the execution of \fBhtags\fP:
.TP
\fBTMPDIR\fP
If this variable is set, its value is used as the directory
to make temporary files. The default is \'/tmp\'.
.TP
\fBGTAGSCONF\fP
If this variable is set, its value is used as the
configuration file. The default is \'$HOME/.globalrc\'.
.TP
\fBGTAGSLABEL\fP
If this variable is set, its value is used as the label
of configuration file. The default is default.
.TP
\fBGTAGSCACHE\fP
If this variable is set, its value is used as the size of
B-tree cache. The default is 5000000 (bytes).
.TP
\fBGTAGSFORCECPP\fP
If this variable is set, each file whose suffix is 'h' is treated
as a C++ source file.
.SH CONFIGURATION
The following configuration variables affect the execution of \fBhtags\fP:
If the \fB--xhtml\fP option is specified then all definitions of
HTML tag are ignored.
Instead, you can customize the appearance using style sheet file
(\'style.css\').
.TP
body_begin(string)
Begin tag for body. The default is ''.
.TP
body_end(string)
End tag for body. The default is ''.
.TP
brace_begin(string)
Begin tag for brace. The default is ''.
.TP
brace_end(string)
End tag for brace. The default is ''.
.TP
colorize_warned_line(boolean)
Colorize warned line using warned_line_begin and warned_line_end.
The default is false.
.TP
comment_begin(string)
Begin tag for comments. The default is ''.
.TP
comment_end(string)
End tag for comments. The default is ''.
.TP
copy_files(boolean)
Copy files instead of linking.
When the \fB-f\fP option is used, \fBhtags\fP make links
of tag files in \'cgi-bin\' directory by default.
.TP
datadir(string)
Shared data directory. The default is '/usr/local/share' but
you can change the value using configure script.
\fBHtags\fP look up template files in the 'gtags' directory
in this data directory.
.TP
definition_header(no|before|right|after)
Position of function header. The default is 'no'.
.TP
disable_grep(boolean)
Disable grep in search form(-f,--form). The default is false.
.TP
dynamic(boolean)
Generate object list dynamically.
.TP
enable_idutils(boolean)
Enable idutils in search form(-f,--form). The default is false.
.TP
flist_fields(number)
Field number of file index. The default is 5.
.TP
full_path(boolean)
List file names with full path in file index.
By default, list just the last component of a path.
.TP
gzipped_suffix(string)
Suffix for compressed html file. The default is 'ghtml'.
.TP
hr(string)
Horizontal rules. The default is '
'.
.TP
htags_options(string)
Default options for \fBhtags\fP. This value is inserted into
the head of arguments.
.TP
include_file_suffixes(comma separated list)
Suffixes of include file. The default is 'h,hxx,hpp,H,inc.php'.
.TP
langmap(comma separated list)
Language mapping. Each comma-separated map consists of
the language name, a colon, and a list of file extensions.
Default mapping is 'c:.c.h,yacc:.y,asm:.s.S,java:.java,cpp:.c++.cc.cpp.cxx.hxx.hpp.C.H,php:.php.php3.phtml'.
.TP
ncol(number)
Columns of line number. The default is 4.
.TP
normal_suffix(string)
Suffix for normal html file. The default is 'html'.
.TP
no_map_file(boolean)
Doesn't generate \'MAP\' and \'FILEMAP\' file. The default is false.
.TP
other_files(boolean)
File index includes not only source files but also other files. The default is false.
.TP
position_begin(string)
Begin tag for position mark. The default is ''.
.TP
position_end(string)
End tag for position mark. The default is ''.
.TP
reserved_begin(string)
Begin tag for reserved word. The default is ''.
.TP
reserved_end(string)
End tag for reserved word. The default is ''.
.TP
script_alias(string)
Script alias for safe cgi script (\fB-S\fP).
.TP
sharp_begin(string)
Begin tag for 'define'. The default is ''.
.TP
sharp_end(string)
End tag for 'define'. The default is ''.
.TP
show_position(boolean)
Show position per function definition. The default is false.
.TP
table_begin(string)
Begin tag for table. The default is ''.
.TP
table_end(string)
End tag for table. The default is '
'.
.TP
table_flist(boolean)
Use tag for file index. The default is false.
.TP
table_list(boolean)
List tags using tag. The default is false.
.TP
tabs(number)
Tab stop. The default is 8.
.TP
title_begin(string)
Begin tag for Title. The default is ''.
.TP
title_end(string)
End tag for Title. The default is '
'.
.TP
warned_line_begin(string)
Begin tag for line which htags warned. The default is ''.
.TP
warned_line_end(string)
End tag for line which htags warned. The default is ''.
.TP
xhtml_version(1.0|1.1)
XHTML version. 1.0 and 1.1 are acceptable. The default is 1.0.
.SH DIAGNOSTICS
\fBHtags\fP exits with a non 0 value if an error occurred, 0 otherwise.
.SH "MESSAGE FORMAT"
Verbose message has important level. The most important level is 0,
the second it 1 and so on. All the message has level numbers leading
blanks.
.SH "SEE ALSO"
\fBgtags-parser\fP(1),
\fBglobal\fP(1),
\fBgtags\fP(1).
.PP
GNU GLOBAL source code tag system
.br
(http://www.gnu.org/software/global/).
.SH BUG
Generated hypertext is VERY LARGE.
In advance, check the space of your disk.
.PP
PHP support is far from complete.
.SH AUTHOR
Tama Communications Corporation.
.SH HISTORY
The \fBhtags\fP command appeared in FreeBSD 2.2.2.