htags(1): make hypertext from source code

NAME

htags - generate hypertext from source code.

SYNOPSIS

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

DESCRIPTION

Htags makes hypertext of C, C++, Yacc, Java, PHP and Assembly source code.

In advance of using this command, you must execute gtags(1) from the root directory of the source tree. Then you can execute htags from the same place. Htags makes an directory named 'HTML' and generates hypertext in it. You can start browsing from 'HTML/index.html'.

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

You must use same parser for both gtags(1) and htags. If you use the default parser, it is not necessary to consider for it.

OPTIONS

The following options are available:

-a, --alphabet: Make an alphabetical function index which is suitable for a large project.
--caution: Include caution message to prohibit downloading.
-c, --compact: Compress html files by gzip(1). You need to set up a web server so that gzip(1) is invoked for each compressed file. See 'HTML/.htaccess' that is generated by htags.
--cvsweb url: Include cvsweb URL. url is used as base of URL. When directory 'CVS' exists in the root directory of source project, content of 'CVS/Repository' is used as relative path from the base.
--cvsweb-cvsroot cvsroot: Specifies cvsroot in cvsweb URL.
-D, --dynamic: 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 directroy.
-d, --dbpath dbpath: Specifies the directory in which 'GTAGS' and 'GRTAGS' exist. The default is the current directory.
-f, --form: Support search form using CGI program. You need to set up a web server, and you cannot move the hypertext from the source directroy.
-F, --frame: Use frame for each part of the contents.
--full-path: List file names with full path in file index. By default, list just the last component of a path.
-g, --gtags: Execute gtags(1) before creating hypertext. The -v, -w and dbpath are passed to gtags.
-h, --func-header [position]: Insert function header for each function. By default, htags doesn't generates it. You can specify the position using position argument, which allows one of before, right and after. The default position is after.
-I, --icon: Use icons instead of text for some links.
--disable-grep: Disable grep in search form(-f,--form).
--gtagsconf file: Load user's configuration from file.
--gtagslabel label: label is used for the label of configuration file. The default is default.
--insert-header file: Insert custom header derived from file after <body> tag.
--insert-footer file: Insert custom footer derived from file before </body> tag.
-m, --main-func name: Specify the main function name. The default is main.
-n, --line-number [columns]: Print line numbers. By default, doesn't print them. The default value of columns is 4.
--no-map-file: Doesn't generate 'MAP' and 'FILEMAP' file. By default, htags generates them.
-o, --other: Pick up not only source files but also other files except for binary files.
--statistics: Print statistics information.
-s, --symbol: Make anchors not only for functions but also other symbols. 'GSYMS' tag file needed.
-S, --secure-cgi cgidir: Write CGI programs into the cgidir 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'.
-t, --title title
-t, --title title: The title of this hypertext. The default is the last; The title of this hypertext. The default is the last component of the current directory.
-T, --table-flist [fields]: Generate file list using <table> tag. The fields is used for field number in a line. The default is 5.
--table-list: List tags using <table> tag.
--tabs number: Tab stop. The default is 8.
-v, --verbose: Verbose mode.
-w, --warning: Print warning messages.
-x, --xhtml [version]: Generate XHTML hypertext instead of HTML. 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 hypertext is generated. The default is the current directory.

EXAMPLES

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

FILES

'GTAGS': Tag file for function definitions.
'GRTAGS': Tag file for function references.
'GSYMS': Tag file for other symbols.
'GPATH': Tag file for path of source files.
'/etc/gtags.conf', '$HOME/.globalrc': Configuration file.
'HTML/index.html': Index file for hypertext.
'HTML/MAP': Mapping file for converting tag into path of hypertext. External system utilize this file.
'HTML/FILEMAP': Mapping file for converting file name into path of hypertext. External system utilize this file.
'HTML/style.css': Style sheet file. This file is generated when the --xhtml option is specified.

ENVIRONMENT

The following environment variables affect the execution of htags:

TMPDIR: If this variable is set, its value is used as the directory to make temporary files. The default is '/tmp'.
GTAGSCONF: If this variable is set, its value is used as the configuration file. The default is '$HOME/.globalrc'.
GTAGSLABEL: If this variable is set, its value is used as the label of configuration file. The default is default.
GTAGSCACHE: If this variable is set, its value is used as the size of btree cache. The default is 500000 (bytes).

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 lookup template files in the 'gtags' directory in this data directory.
htags_options(string): Default options for htags. This value is inserted into the head of arguments.
xhtml_version(1.0|1.1): XHTML version. 1.0 and 1.1 are acceptable. The default is 1.0.
body_begin(string): Begin tag for body. The default is '<body text=#191970 bgcolor=#f5f5dc vlink=gray>'.
body_end(string): End tag for body. The default is '</body>'.
table_begin(string): Begin tag for table. The default is '<table>'.
table_end(string): End tag for table. The default is '</table>'.
title_begin(string)
title_begin(string): Begin tag for Title. The default is '<h1><font color=#cc0000>'.
title_end(string)
title_end(string): End tag for Title. The default is '</font></h1>'.
comment_begin(string): Begin tag for comments. The default is '<i><font color=green>'.
comment_end(string): End tag for comments. The default is '</font></i>'.
dynamic(bool): Generate object list dynamically.
sharp_begin(string): Begin tag for 'define'. The default is '<font color=darkred>'.
sharp_end(string): End tag for 'define'. The default is '</font>'.
brace_begin(string): Begin tag for brace. The default is '<font color=red>'.
brace_end(string): End tag for brace. The default is '</font>'.
reserved_begin(string): Begin tag for reserved word. The default is '<b>'.
reserved_end(string): End tag for reserved word. The default is '</b>'.
position_begin(string): Begin tag for posiotion mark. The default is '<font color=gray>'.
position_end(string): End tag for posiotion mark. The default is '</font>'.
colorize_warned_line(boolean): Colorize warned line using warned_line_begin and warned_line_end. The default is false.
warned_line_begin(string): Begin tag for line which htags warned. The default is '<span style="background-color:yellow">'.
warned_line_end(string): End tag for line which htags warned. The default is '</span>'.
hr(string): Horizontal rules. The default is '<hr>'.
ncol(number): Columns of line number. The default is 4.
tabs(number): Tab stop. The default is 8.
flist_fields(number): Field number of file index. The default is 5.
full_path(boolean): List file names with full path in file index. By default, list just the last component of a path.
table_list(boolean): List tags using <table> tag. The default is false.
table_flist(boolean): Use <table> tag for file index. The default is false.
normal_suffix(string): Suffix for normal html file. The default is 'html'.
no_map_file(boolean): Doesn't generate 'MAP' file. The default is false.
gzipped_suffix(string): Suffix for compressed html file. The default is 'ghtml'.
script_alias(string): Script alias for safe cgi script (-S).
show_position(boolean): Show position per function definition. The default is false.
definition_header(no|before|right|after): Position of function header. The default is 'no'.
other_files(boolean): File index includes not only source files but also other files. The default is false.
disable_grep(boolean): Disable grep in search form(-f,--form). The default is false.
enable_idutils(boolean): Enable idutils in search form(-f,--form). The default is false.
include_file_suffixes(comma separated list): Suffixes of include file. The default is 'h,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.cpp.cxx.hxx.hpp.C.H,php:.php.php3.phtml'.
copy_files(boolean): Copy files instead of linking. When the -f option is used, htags make links of tag files in 'cgi-bin' directory by default.

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

EXAMPLES

FILES

ENVIRONMENT

CONFIGURATION

DIAGNOSTICS

MESSAGE FORMAT

SEE ALSO

BUG

AUTHOR

HISTORY