NAME¶
htags - generate hypertext from source code.
SYNOPSIS¶
htags [-acCDfFghInosTvwx][-d
dbpath][-m
name][-S
cgidir][-t
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 by
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¶
If you are new on htags, it is recommended to invoke with the
--suggest
option. With the option,
htags use popular options instead of you.
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.
- -C
- Make compressed html files with a html.gz suffix. Debian systems
can usually uncompress these transparently without the need for a CGI
helper.
- --cvsweb url
- Include cvsweb URL. url 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.
- --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 directory.
- -d, --dbpath dbpath
- Specifies the directory in which ´GTAGS´ and
´GRTAGS´ exist. The default is the current directory.
- --disable-grep
- Disable grep in the search form(-f,--form).
- -F, --frame
- Use frame for each part of the contents.
- -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 directory.
- --full-path
- List file names with full path in the 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.
- --gtagsconf file
- Load user's configuration from file.
- --gtagslabel label
- label is used for the label of configuration file. The default is
default.
- -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.
- --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 order of items in the top page. The spec is a string
consists of item signs in order. Each sign means as follows: c:
caution, s: search form, m: mains, d: definition,
f: files. The default is csmdf.
- -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 line numbers. 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.
- -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´.
- -s, --symbol
- Make anchors not only for object definitions and references but also other
symbols.
- --statistics
- Print statistics information.
- --suggest
- Htags selects popular options instead of beginners. It is
equivalent to '-afghInosTxv --show-position' now.
- -T, --table-flist[=fields]
- Generate file list using <table> tag. The fields is used for
field number in a line. The default is 5.
- -t, --title title
- The title of this hypertext. The default is the last component of
the current directory.
- --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 'Welcome to XXX source tour!'
$ firefox HTML/index.html
$ htags --suggest
FILES¶
- ´GTAGS´
- Tag file for object definitions.
- ´GRTAGS´
- Tag file for object 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 systems
can utilize this file.
- ´HTML/FILEMAP´
- Mapping file for converting file name into path of hypertext. External
systems can 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 B-tree cache.
The default is 5000000 (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´).
- 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>'.
- brace_begin(string)
- Begin tag for brace. The default is '<font color=red>'.
- brace_end(string)
- End tag for brace. The default is '</font>'.
- colorize_warned_line(boolean)
- Colorize warned line using warned_line_begin and warned_line_end. The
default is false.
- 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>'.
- 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.
- datadir(string)
- Shared data directory. The default is '/usr/local/share' but you can
change the value using configure script. Htags look up template
files in the 'gtags' directory in this data directory.
- definition_header(no|before|right|after)
- Position of function header. The default is 'no'.
- disable_grep(boolean)
- Disable grep in search form(-f,--form). The default is false.
- dynamic(boolean)
- Generate object list dynamically.
- enable_idutils(boolean)
- Enable idutils in search form(-f,--form). The default is false.
- 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.
- gzipped_suffix(string)
- Suffix for compressed html file. The default is 'ghtml'.
- hr(string)
- Horizontal rules. The default is '<hr>'.
- 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 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'.
- ncol(number)
- Columns of line number. The default is 4.
- normal_suffix(string)
- Suffix for normal html file. The default is 'html'.
- no_map_file(boolean)
- Doesn't generate ´MAP´ and ´FILEMAP´ file. The
default is false.
- other_files(boolean)
- File index includes not only source files but also other files. The
default is false.
- position_begin(string)
- Begin tag for position mark. The default is '<font
color=gray>'.
- position_end(string)
- End tag for position mark. 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>'.
- script_alias(string)
- Script alias for safe cgi script (-S).
- sharp_begin(string)
- Begin tag for 'define'. The default is '<font color=darkred>'.
- sharp_end(string)
- End tag for 'define'. The default is '</font>'.
- show_position(boolean)
- Show position per function definition. The default is false.
- table_begin(string)
- Begin tag for table. The default is '<table>'.
- table_end(string)
- End tag for table. The default is '</table>'.
- table_flist(boolean)
- Use <table> tag for file index. The default is false.
- table_list(boolean)
- List tags using <table> tag. The default is false.
- tabs(number)
- Tab stop. The default is 8.
- title_begin(string)
- Begin tag for Title. The default is '<h1><font
color=#cc0000>'.
- title_end(string)
- End tag for Title. The default is '</font></h1>'.
- 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>'.
- 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.
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.
SEE ALSO¶
gtags-parser(1),
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.
AUTHOR¶
Tama Communications Corporation.
HISTORY¶
The
htags command appeared in FreeBSD 2.2.2.
