HTAGS(1)

NAME
htags - generate a hypertext from a set of source files.

SYNOPSIS
htags [-acDfFghInosTvwx][-d dbpath][-m name][-t title][dir]

DESCRIPTION
Htags generates a hypertext from a set of source files of C, C++, Yacc, Java, PHP and Assembly.

In advance of using this command, you should execute gtags(1) in the root directory of a source project. Then you can execute htags in the same place. Htags makes a directory named 'HTML', and puts a hypertext in it. You can start browsing at 'HTML/index.html'.

Since htags generates a static hypertext as long as the -D or -f option is not specified, you can move it anywhere and browse it by any browser without any HTTP server.

This command has so many options. If you are new on htags, it is recommended to use --suggest option. With the option, htags chooses popular options on behalf of you.

OPTIONS
The following options are available:

-a, --alphabet
    Make an alphabetical index suitable for a large project.

--auto-completion[=limit]
    Enable auto completion facility for the input form. If limit is specified, number of candidates is limited to the value. Please note that this function requires javascript language in your browser.

--caution
    Display a caution message on the top page.

--cflow cflowfile
    Add a call tree by cflow(1). cflowfile must be posix format. If you use GNU cflow, invoke the command at the project root directory with --format=posix option. This option is deprecated. Please use the --call-tree or --callee-tree instead.

--call-tree callfile
    Add a call tree by cflow(1). callfile must be posix format. If you use GNU cflow, invoke the command at the project root directory with --format=posix option.

--callee-tree calleefile
    Add a callee tree by cflow(1). calleefile must be posix format. If you use GNU cflow, invoke the command at the project root directory with --format=posix and --reverse option.

-c, --compact
    Compress html files by gzip(1). You need to configure HTTP server so that gzip(1) is invoked for each compressed file. See 'HTML/.htaccess' that is generated by htags.

--cvsweb url
    Add a link to cvsweb. url is used as the base of URL. When directory 'CVS' exists in the root directory of the project, the content of 'CVS/Repository' is used as the relative path from the base.

--cvsweb-cvsroot cvsroot
    Specify cvsroot in cvsweb URL.

-D, --dynamic
    Generate a tag list dynamically using CGI program. This option decrease both the size and generation time of the hypertext. You need to start a HTTP server for it.

-d, --dbpath dbpath
    Specify a directory in which 'GTAGS' exists. The default is the current directory.

--disable-grep
    Disable grep in the search form(-f,--form).

--disable-idutils
    Disable idutils in the search form(-f,--form).

-F, --frame
    Use frames for the top page.

-f, --form
    Add a search form using CGI program. You need to start a HTTP server for it.

--fixed-guide
    Put a fixed guide at the bottom of the screen of the browser.

--full-path
    Use full path name in the file index. By default, use just the last component of a path.

-g, --gtags
    Execute gtags(1) before starting job. The -v, -w and dbpath options are passed to gtags.

--gtagsconf file
    Set environment variable GTAGSCONF to file.

--gtagslabel label
    Set environment variable GTAGSLABEL to label.

-h, --func-header[=position]
    Insert a function header for each function. By default, htags doesn't generate them. You can specify the position using position argument, which allows one of before, right and after. The default position is after.

--html-header file
    Insert a header record derived from file into the HTML header of each file.

-I, --icon
    Use icons instead of text for some links.

--insert-footer file
    Insert a custom footer derived from file before </body> tag of each file.

--insert-header file
    Insert a custom header derived from file after <body> tag of each file.

--item-order spec
    Specify the order of the items in the top page. The spec is a string consisting of item signs in order. Each sign means as follows: c: caution; s: search form; m: mains; d: definition; f: files; t: call tree. The default is csmdf.

-m, --main-func name
    Specify start-up function name. The default is main.

-n, --line-number[=columns]
    Print line numbers. By default, doesn't print line numbers. The default value of columns is 4.

--map-file
    Generate 'MAP' file.

-o, --other
    Pick up not only source files but also other files for the file index.

--overwrite-key
    Allow overwrite of an existing key with the --system-cgi option.

--system-cgi key
    Use system CGI script. The key must be unique in the site. At the first time, you should (1) copy the CGI script written by this command into a system CGI directory, and (2) execute bless.sh script in the HTML directory. Please see 'bless.sh' for details.

-s, --symbol
    Make anchors not only for definitions and references but also other symbols.

--show-position
    Print the position string per function definition. The string can be interpreted by general editors in UNIX. The default is false.

--statistics
    Print statistics information.

--suggest
    Htags chooses popular options on behalf of beginners. It is equivalent to '-aghInosTv --show-position --fixed-guide' now.

--suggest2
    Htags chooses popular options on behalf of beginners. This option enables frame, AJAX and CGI facility in addition to the facilities by the --suggest option. It is equivalent to '--suggest -DfF --auto-completion --tree-view=filetree' now.

-T, --table-flist[=rows]
    Use <table> tag to display the file index. You can optionally specify the number of rows. The default is 5.

-t, --title title
    Title of the hypertext. The default is the last component of the path of the current directory.

--table-list
    Use <table> tag to display the tag list.

--tree-view[=type]
    Use treeview for the file index. Please note that this function requires javascript language in your browser. Possible values of type are as follows: treeview, filetree, treeview-red, treeview-black, treeview-gray, treeview-famfamfam. The default is treeview.

-v, --verbose
    Verbose mode.

-w, --warning
    Print warning messages.

-x, --xhtml[=version]
    Generate XHTML hypertext. This is the default. If the --frame option is specified then generate XHTML-1.0 Frameset for index.html and generate XHTML-1.0 Transitional for other files, else if version is 1.1 or config variable xhtml_version is set to 1.1 then generate XHTML-1.1 else XHTML 1.0 Transitional.

dir The directory in which the result of this command is stored. The default is the current directory.

EXAMPLES
$ gtags -v
$ htags -sanohITvt 'Welcome to XXX source tour!'
$ firefox HTML/index.html

$ htags --suggest

FILES

'GTAGS'
    Tag file for definitions.

'GRTAGS'
    Tag file for references.

'GPATH'
    Tag file for source files.

'$HOME/.globalrc', '/etc/gtags.conf', '[sysconfdir]/gtags.conf'
    Configuration files.

'HTML/index.html'
    Start-up file.

'HTML/MAP'
    Mapping file for converting tag name into the path of tag list.

'HTML/FILEMAP'
    Mapping file for converting file name into the path of the file.

'HTML/style.css'
    Style sheet file. This file is generated when the --xhtml option is specified.

'HTML/.htaccess'
    Local configuration file for Apache. This file is generated when the -f, -D or -c option is specified.

'HTML/GTAGSROOT'
    If this file exists, CGI program 'global.cgi' sets environment variable GTAGSROOT to the contents of it. If you move directory 'HTML' from the original place, please make this file.

'/usr/local/var/gtags/sitekeys'
    Site key database directory used for the --system-cgi. Though its mode is set as 755 by default, it is left to the system administrator.

ENVIRONMENT
The following environment variables affect the execution of htags:

TMPDIR
    The location used to stored temporary files. The default is '/tmp'.

GTAGSCONF
    Configuration file. The default is '$HOME/.globalrc'.

GTAGSLABEL
    Configuration label. The default is default.

GTAGSCACHE
    The size of B-tree cache. The default is 50000000 (bytes).

GTAGSFORCECPP
    If this variable is set, each file whose suffix is 'h' is treated as a C++ source file.

CONFIGURATION
The following configuration variables affect the execution of htags: If the --xhtml option is specified then all definitions of HTML tag are ignored. Instead, you can customize the appearance using style sheet file ('style.css').

datadir(string)
    Shared data directory. The default is '/usr/local/share' but you can change the value using configure script. Htags looks up template files there.

gzipped_suffix(string)
    Suffix for compressed html file. The default is 'ghtml'.

htags_options(string)
    Default options for htags. This value is inserted into the head of arguments.

include_file_suffixes(comma separated list)
    Suffixes of include files. The default is 'h,hh,hxx,hpp,H,inc.php'.

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.hh.cpp.cxx.hxx.hpp.C.H,php:.php.php3.phtml'.

ncol(number)
    Columns of line number. The default is 4.

normal_suffix(string)
    Suffix for normal html file. The default is 'html'.

script_alias(string)
    Script alias for system cgi script (--system-cgi).

tabs(number)
    Tab stop. The default is 8.

xhtml_version(1.0|1.1)
    XHTML version. 1.0 and 1.1 are acceptable. The default is 1.0.

DIAGNOSTICS
Htags exits with a non 0 value if an error occurred, 0 otherwise.

SEE ALSO
global(1), gtags(1).

GNU GLOBAL source code tag system
(http://www.gnu.org/software/global/).

BUG
Generated hypertext is VERY LARGE. In advance, check the space of your disk.

PHP support is far from complete.

The -f, -D or -c option generates CGI programs. If you open the result to the public, please recognize the security dangers.

AUTHOR
Shigio YAMAGUCHI, Hideki IWAMOTO and others.

HISTORY
The htags command appeared in FreeBSD 2.2.2.