htags(1) - f14

1HTAGS(1)                    General Commands Manual                   HTAGS(1)
2
3
4

NAME

6       htags - generate hypertext from source code.
7

SYNOPSIS

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

DESCRIPTION

12       Htags  makes  hypertext  of C, C++, Yacc, Java, PHP and Assembly source
13       code.
14
15       In advance of using this command, you must execute  gtags(1)  from  the
16       root directory of the source tree.  Then you can execute htags from the
17       same place.  Htags makes an directory named ´HTML´ and generates hyper‐
18       text in it.  You can start browsing from ´HTML/index.html´.
19
20       Since  htags  generates static hypertext as long as the -D or -f option
21       is not specified, you can move it anywhere and browse it by any browser
22       without web server.
23
24       You  must  use same parser for both gtags(1) and htags.  If you use the
25       default parser, it is not necessary to consider for it.
26

OPTIONS

28       If you are new on htags, it is recommended to invoke with the --suggest
29       option.  With the option, htags use popular options instead of you.
30       The following options are available:
31
32       -a, --alphabet
33              Make  an  alphabetical  function  index  which is suitable for a
34              large project.
35
36       --caution
37              Include caution message to prohibit downloading.
38
39       -c, --compact
40              Compress html files  by gzip(1).  You  need  to  set  up  a  web
41              server so that gzip(1) is invoked for each compressed file.  See
42              ´HTML/.htaccess´ that is generated by htags.
43
44       --cvsweb url
45              Include cvsweb URL. url is used as base of URL.  When  directory
46              ´CVS´  exists  in the root directory of source project, the con‐
47              tent of ´CVS/Repository´ is used as the relative path  from  the
48              base.
49
50       --cvsweb-cvsroot cvsroot
51              Specifies cvsroot in cvsweb URL.
52
53       -D, --dynamic
54              Generate   object  lists  dynamically  using  CGI  program.   By
55              default, object lists are  generated  statically.   Though  this
56              option  decrease  both  the  size and the generation time of the
57              hypertext, you need to set up a web server, and you cannot  move
58              the hypertext from the source directory.
59
60       -d, --dbpath dbpath
61              Specifies the directory in which ´GTAGS´ and ´GRTAGS´ exist. The
62              default is the current directory.
63
64       --disable-grep
65              Disable grep in the search form(-f,--form).
66
67       -F, --frame
68              Use frame for each part of the contents.
69
70       -f, --form
71              Support search form using CGI program.  You need to set up a web
72              server, and you cannot move the hypertext from the source direc‐
73              tory.
74
75       --full-path
76              List file names with full path in the file index.   By  default,
77              list just the last component of a path.
78
79       -g, --gtags
80              Execute  gtags(1)  before  creating  hypertext.   The -v, -w and
81              dbpath are passed to gtags.
82
83       --gtagsconf file
84              Load user's configuration from file.
85
86       --gtagslabel label
87              label is used for the label of configuration file.  The  default
88              is default.
89
90       -h, --func-header[=position]
91              Insert  function  header  for  each function.  By default, htags
92              doesn't generates it.  You can specify the position using  posi‐
93              tion argument, which allows one of before, right and after.  The
94              default position is after.
95
96       -I, --icon
97              Use icons instead of text for some links.
98
99       --insert-footer file
100              Insert custom footer derived from file before </body> tag.
101
102       --insert-header file
103              Insert custom header derived from file after <body> tag.
104
105       --item-order spec
106              Specify order of items in the top page.  The spec  is  a  string
107              consists of item signs in order.  Each sign means as follows: c:
108              caution, s: search form, m: mains, d: definition, f: files.  The
109              default is csmdf.
110
111       -m, --main-func name
112              Specify the main function name. The default is main.
113
114       -n, --line-number[=columns]
115              Print line numbers. By default, doesn't print line numbers.  The
116              default value of columns is 4.
117
118       --no-map-file
119              Doesn't generate ´MAP´ and ´FILEMAP´ file.   By  default,  htags
120              generates them.
121
122       -o, --other
123              Pick  up  not  only source files but also other files except for
124              binary files.
125
126       -S, --secure-cgi cgidir
127              Write CGI programs into the cgidir to realize a centralised  CGI
128              program.   Script alias is ´/cgi-bin´ by default.  You can over‐
129              write  this  value  using  config   variable   script_alias   in
130              ´gtags.conf´.
131
132       -s, --symbol
133              Make  anchors not only for object definitions and references but
134              also other symbols.
135
136       --statistics
137              Print statistics information.
138
139       --suggest
140              Htags selects popular  options  instead  of  beginners.   It  is
141              equivalent to '-afghInosTxv --show-position' now.
142
143       -T, --table-flist[=fields]
144              Generate  file  list  using <table> tag.  The fields is used for
145              field number in a line. The default is 5.
146
147       -t, --title title
148              The title of this hypertext. The default is the  last  component
149              of the current directory.
150
151       --table-list
152              List tags using <table> tag.
153
154       --tabs number
155              Tab stop. The default is 8.
156
157       -v, --verbose
158              Verbose mode.
159
160       -w, --warning
161              Print warning messages.
162
163       -x, --xhtml[=version]
164              Generate XHTML hypertext instead of HTML.  If the --frame option
165              is specified then generate XHTML-1.0 Frameset for index.html and
166              generate XHTML-1.0 Transitional for other files, else if version
167              is 1.1 or config variable xhtml_version is set to 1.1 then  gen‐
168              erate XHTML-1.1 else XHTML 1.0 Transitional.
169
170       dir    The  directory  in which hypertext is generated.  The default is
171              the current directory.
172

EXAMPLES

174            $ gtags -v
175            $ htags -sanohITvt 'Welcome to XXX source tour!'
176            $ firefox HTML/index.html
177
178            $ htags --suggest
179

FILES

181       ´GTAGS´
182              Tag file for object definitions.
183
184       ´GRTAGS´
185              Tag file for object references.
186
187       ´GSYMS´
188              Tag file for other symbols.
189
190       ´GPATH´
191              Tag file for path of source files.
192
193       ´/etc/gtags.conf´, ´$HOME/.globalrc´
194              Configuration file.
195
196       ´HTML/index.html´
197              Index file for hypertext.
198
199       ´HTML/MAP´
200              Mapping file for converting tag into path of hypertext.   Exter‐
201              nal systems can utilize this file.
202
203       ´HTML/FILEMAP´
204              Mapping  file  for  converting file name into path of hypertext.
205              External systems can utilize this file.
206
207       ´HTML/style.css´
208              Style sheet file. This file is generated when the --xhtml option
209              is specified.
210

ENVIRONMENT

212       The following environment variables affect the execution of htags:
213
214       TMPDIR If  this  variable is set, its value is used as the directory to
215              make temporary files. The default is ´/tmp´.
216
217       GTAGSCONF
218              If this variable is set, its value is used as the  configuration
219              file. The default is ´$HOME/.globalrc´.
220
221       GTAGSLABEL
222              If  this variable is set, its value is used as the label of con‐
223              figuration file. The default is default.
224
225       GTAGSCACHE
226              If this variable is set, its value is used as the size of B-tree
227              cache. The default is 50000000 (bytes).
228
229       GTAGSFORCECPP
230              If  this  variable  is  set,  each  file  whose suffix is 'h' is
231              treated as a C++ source file.
232

CONFIGURATION

234       The following configuration variables affect the execution of htags: If
235       the  --xhtml  option  is specified then all definitions of HTML tag are
236       ignored.  Instead, you can customize the appearance using  style  sheet
237       file (´style.css´).
238
239       body_begin(string)
240              Begin   tag   for  body.  The  default  is  '<body  text=#191970
241              bgcolor=#f5f5dc vlink=gray>'.
242
243       body_end(string)
244              End tag for body. The default is '</body>'.
245
246       brace_begin(string)
247              Begin tag for brace. The default is '<font color=red>'.
248
249       brace_end(string)
250              End tag for brace. The default is '</font>'.
251
252       colorize_warned_line(boolean)
253              Colorize    warned    line    using    warned_line_begin     and
254              warned_line_end.  The default is false.
255
256       comment_begin(string)
257              Begin tag for comments. The default is '<i><font color=green>'.
258
259       comment_end(string)
260              End tag for comments. The default is '</font></i>'.
261
262       copy_files(boolean)
263              Copy  files  instead  of  linking.   When the -f option is used,
264              htags make links of tag files in ´cgi-bin´ directory by default.
265
266       datadir(string)
267              Shared data directory. The default is '/usr/local/share' but you
268              can change the value using configure script.  Htags look up tem‐
269              plate files in the 'gtags' directory in this data directory.
270
271       definition_header(no|before|right|after)
272              Position of function header. The default is 'no'.
273
274       disable_grep(boolean)
275              Disable grep in search form(-f,--form). The default is false.
276
277       dynamic(boolean)
278              Generate object list dynamically.
279
280       enable_idutils(boolean)
281              Enable idutils in search form(-f,--form). The default is false.
282
283       flist_fields(number)
284              Field number of file index. The default is 5.
285
286       full_path(boolean)
287              List file names with full path in file index.  By default,  list
288              just the last component of a path.
289
290       gzipped_suffix(string)
291              Suffix for compressed html file. The default is 'ghtml'.
292
293       hr(string)
294              Horizontal rules. The default is '<hr>'.
295
296       htags_options(string)
297              Default  options for htags. This value is inserted into the head
298              of arguments.
299
300       include_file_suffixes(comma separated list)
301              Suffixes of include file. The default is 'h,hxx,hpp,H,inc.php'.
302
303       langmap(comma separated list)
304              Language mapping. Each comma-separated map consists of the  lan‐
305              guage  name,  a  colon,  and a list of file extensions.  Default
306              mapping                                                       is
307              'c:.c.h,yacc:.y,asm:.s.S,java:.java,cpp:.c++.cc.cpp.cxx.hxx.hpp.C.H,php:.php.php3.phtml'.
308
309       ncol(number)
310              Columns of line number. The default is 4.
311
312       normal_suffix(string)
313              Suffix for normal html file. The default is 'html'.
314
315       no_map_file(boolean)
316              Doesn't generate ´MAP´ and ´FILEMAP´ file. The default is false.
317
318       other_files(boolean)
319              File index includes not only source files but also other  files.
320              The default is false.
321
322       position_begin(string)
323              Begin tag for position mark. The default is '<font color=gray>'.
324
325       position_end(string)
326              End tag for position mark. The default is '</font>'.
327
328       reserved_begin(string)
329              Begin tag for reserved word. The default is '<b>'.
330
331       reserved_end(string)
332              End tag for reserved word. The default is '</b>'.
333
334       script_alias(string)
335              Script alias for safe cgi script (-S).
336
337       sharp_begin(string)
338              Begin tag for 'define'. The default is '<font color=darkred>'.
339
340       sharp_end(string)
341              End tag for 'define'. The default is '</font>'.
342
343       show_position(boolean)
344              Show position per function definition. The default is false.
345
346       table_begin(string)
347              Begin tag for table. The default is '<table>'.
348
349       table_end(string)
350              End tag for table. The default is '</table>'.
351
352       table_flist(boolean)
353              Use <table> tag for file index. The default is false.
354
355       table_list(boolean)
356              List tags using <table> tag. The default is false.
357
358       tabs(number)
359              Tab stop. The default is 8.
360
361       title_begin(string)
362              Begin tag for Title. The default is '<h1><font color=#cc0000>'.
363
364       title_end(string)
365              End tag for Title. The default is '</font></h1>'.
366
367       warned_line_begin(string)
368              Begin  tag  for  line  which htags warned. The default is '<span
369              style="background-color:yellow">'.
370
371       warned_line_end(string)
372              End tag for line which htags warned. The default is '</span>'.
373
374       xhtml_version(1.0|1.1)
375              XHTML version. 1.0 and 1.1 are acceptable. The default is 1.0.
376

DIAGNOSTICS

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

MESSAGE FORMAT

381       Verbose message has important level. The most important level is 0, the
382       second  it  1  and  so  on.  All  the message has level numbers leading
383       blanks.
384

BUG

392       Generated hypertext is VERY LARGE.  In advance, check the space of your
393       disk.
394
395       PHP support is far from complete.
396

AUTHOR

398       Tama Communications Corporation.
399

HISTORY

401       The htags command appeared in FreeBSD 2.2.2.
402
403
404
405GNU Project                     September 2008                        HTAGS(1)