Ubuntu Manpage: htags - generate a hypertext from a set of source files

NAME

       htags - generate a hypertext from a set of source files

SYNOPSIS

       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 http://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´
              Configuration data for GNU GLOBAL.  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.

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.

AUTHOR

       Shigio YAMAGUCHI, Hideki IWAMOTO and others.

HISTORY

       The htags command appeared in FreeBSD 2.2.2.