htags (1)
Leading comments
This file is generated automatically by convert.pl from htags/manual.in.
NAME
htags - generate a hypertext from a set of source filesSYNOPSIS
htags [-aDfFghInosTvw][-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 neither -D nor -f option is not specified, you can move it anywhere and browse it by any browser without any HTTP server. If you use -D or -f option, you need to use HTTP server. Though any HTTP server is available, htags-server(1) is recommended.
This command has so many options. If you are new to htags, it is recommended to use --suggest option. With that option, htags chooses popular options on your behalf.
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 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 the --format=posix option. This option is deprecated; please use --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 the --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 the --format=posix and --reverse options.
- --colorize-warned-line
- Use color to highlight warned lines.
- --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. Though this option decreases both the size and generation time of hypertext, you need to start up HTTP server.
- -d, --dbpath dbpath
- Specify the 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 choose the position using position, which allows one of 'before', 'right' or 'after' (default).
- --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 custom footer derived from file before </body> tag.
- --insert-header file
- Insert custom header derived from file after <body> tag.
- --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': definitions; 'f': files; 't': call tree. The default is 'csmdf'.
- -m, --main-func name
- Specify startup function name; the default is 'main'.
- --map-file
- Generate file 'MAP'.
- -n, --line-number[=columns]
- Print line numbers. By default, don't print line numbers. The default value of columns is 4.
- --no-order-list
- Numbers are not given in list form.
- -o, --other
- Pick up not only source files but also other files for the file index.
- -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 -aghInosTxv --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.
- --tabs cols
- Tab stops. The default is 8.
- --table-list
- Use <table> tag to display the tag list.
- --tree-view[=type]
- Use treeview for the file index. Please note 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.
- 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 --suggest2 $ htags-server >& log & $ firefox 127.0.0.1:8000
FILES
- 'GTAGS'
- Tag file for definitions.
- 'GRTAGS'
- Tag file for references.
- 'GPATH'
- Tag file for source files.
- 'gtags.conf', '$HOME/.globalrc'
- See gtags.conf(5).
- 'HTML/FILEMAP'
- Mapping file for converting file name into the path of the file.
- '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.
- 'HTML/.htaccess'
- Local configuration file for Apache. This file is generated when the -f or -D options are specified.
- 'HTML/index.html'
- Start-up file.
- 'HTML/MAP'
- Mapping file for converting tag name into the path of tag list.
- 'HTML/style.css'
- Style sheet file.
- '/usr/local/share/gtags/style.css.tmpl'
- The template of the style sheet file ('HTML/style.css').
ENVIRONMENT
The following environment variables affect the execution of htags:
- GTAGSCACHE
- The size of the B-tree cache. The default is 50000000 (bytes).
- GTAGSCONF
- Configuration file.
- GTAGSLABEL
- Configuration label. The default is 'default'.
- HTAGS_OPTIONS
- The value of this variable is inserted in the head of arguments.
- TMPDIR
- The location used to stored temporary files. The default is '/tmp'.
- 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:
- 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 in the 'gtags' directory in this data directory.
- 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'.
DIAGNOSTICS
Htags exits with a non-0 value if an error occurred, 0 otherwise.SEE ALSO
htags-server(1), global(1), gtags(1), gtags.conf(5).
GNU GLOBAL source code tag system
(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 and -D options generate CGI programs. If you open the hypertext to the public, please recognize security dangers.
Htags does not support plug-in parser.