1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
|
@c This file is generated automatically by convert.pl from htags/manual.in.
@unnumberedsubsec NAME
htags - generate hypertext from source code.
@unnumberedsubsec SYNOPSIS
@noindent
@quotation
htags [-a][-c][-D][-f][-F][-g][-n][-o][-s][-v][-w][-x][-d dbpath][-m name][-S cgidir][-t title][htmldir]@*
@end quotation
@unnumberedsubsec 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 @file{HTML} and generates
hypertext in it.
You can start browsing from @file{HTML/index.html}.
Since htags generates static hypertext as long as
the @samp{-D} or @samp{-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.
@unnumberedsubsec OPTIONS
The following options are available:
@table @asis
@item @samp{-a}, @samp{--alphabet}
Make an alphabetical function index which is suitable
for a large project.
@item @samp{--caution}
Include caution message to prohibit downloading.
@item @samp{-c}, @samp{--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 @file{HTML/.htaccess} that is generated by htags.
@item @samp{--cvsweb} url
Include cvsweb URL. url is used as base of URL.
@item @samp{--cvsweb-cvsroot} cvsroot
Specifies cvsroot in cvsweb URL.
@item @samp{-D}, @samp{--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.
@item @samp{-d}, @samp{--dbpath} dbpath
Specifies the directory in which @file{GTAGS} and @file{GRTAGS}
exist. The default is the current directory.
@item @samp{-f}, @samp{--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.
@item @samp{-F}, @samp{--frame}
Use frame for each part of the contents.
@item @samp{-g}, @samp{--gtags}
Execute gtags(1) before creating hypertext.
The @samp{-v}, @samp{-w} and dbpath are passed to gtags.
@item @samp{--gtagsconf} file
Load user's configuration from file.
@item @samp{--gtagslabel} label
label is used for the label of configuration file.
The default is @code{default}.
@item @samp{--insert-header} file
Insert custom header derived from file after <body> tag.
@item @samp{--insert-footer} file
Insert custom footer derived from file before </body> tag.
@item @samp{-m}, @samp{--main-func} name
Specify the main function name. The default is @code{main}.
@item @samp{-n}, @samp{--line-number}
Print line numbers. By default, doesn't print them.
@item @samp{--no-map-file}
Doesn't generate @file{MAP} and @file{FILEMAP} file.
By default, htags generates them.
@item @samp{-o}, @samp{--other}
Pick up not only source files but also other files except for
binary files.
@item @samp{--statistics}
Print statistics information.
@item @samp{--style-sheet} file
Load style sheet file and insert it into <head> tag.
If you use the @samp{--xhtml} option, you should use
@file{style.css} instead.
@item @samp{-s}, @samp{--symbol}
Make anchors not only for functions but also other symbols.
@file{GSYMS} tag file needed.
@item @samp{-S}, @samp{--secure-cgi} cgidir
Write CGI programs into the cgidir to realize
a centralised CGI program.
Script alias is @file{/cgi-bin} by default.
You can overwrite this value using config variable
@code{script_alias} in @file{gtags.conf}.
@item @samp{-t}, @samp{--title} title
The title of this hypertext. The default is the last
component of the current directory.
@item @samp{-v}, @samp{--verbose}
Verbose mode.
@item @samp{-w}, @samp{--warning}
Print warning messages.
@item @samp{-x}, @samp{--xhtml}
Generate XHTML hypertext instead of HTML.
If the @samp{--frame} option is specified then
generate XHTML-1.0 Frameset for index.html
and generate XHTML-1.0 Transitional for other files,
else if config variable
@code{xhtml_version} is set to @code{1.1} then generate
XHTML-1.1 else XHTML 1.0 Transitional.
@item htmldir
The directory in which hypertext is generated.
The default is the current directory.
@end table
@unnumberedsubsec EXAMPLES
@example
$ cd /usr/src/sys
# gtags -v
# htags -fFnvat 'Welcom to FreeBSD kernel source tour!'
$ lynx HTML/index.html
$ htags -v --gtags
$ awk '$1 == "main" @{print $2@}' HTML/MAP
D/348.html
$ lynx HTML/D/348.html
$ cd global
$ htags -gv --cvsweb=http://savannah.gnu.org/cgi-bin/viewcvs/global/global/
@end example
@unnumberedsubsec FILES
@table @asis
@item @file{GTAGS}
Tag file for function definitions.
@item @file{GRTAGS}
Tag file for function references.
@item @file{GSYMS}
Tag file for other symbols.
@item @file{GPATH}
Tag file for path of source files.
@item @file{/etc/gtags.conf}, @file{$HOME/.globalrc}
Configuration file.
@item @file{HTML/index.html}
Index file for hypertext.
@item @file{HTML/MAP}
Mapping file for converting tag into path of hypertext.
External system utilize this file. See EXAMPLES.
@item @file{HTML/FILEMAP}
Mapping file for converting file name into path of hypertext.
External system utilize this file.
@item @file{HTML/style.css}
Style sheet file. This file is generated when the @samp{--xhtml}
option is specified.
@end table
@unnumberedsubsec ENVIRONMENT
The following environment variables affect the execution of htags:
@table @asis
@item @var{TMPDIR}
If this variable is set, its value is used as the directory
to make temporary files. The default is @file{/tmp}.
@item @var{GTAGSCONF}
If this variable is set, its value is used as the
configuration file. The default is @file{$HOME/.globalrc}.
@item @var{GTAGSLABEL}
If this variable is set, its value is used as the label
of configuration file. The default is @code{default}.
@item @var{GTAGSCACHE}
If this variable is set, its value is used as the size of
btree cache. The default is 500000 (bytes).
@end table
@unnumberedsubsec CONFIGURATION
The following configuration variables affect the execution of htags:
If the @samp{--xhtml} option is specified then all definitions of
HTML tag are ignored.
Instead, you can customize the appearance using style sheet file
(@file{style.css}).
@table @asis
@item @code{datadir}(string)
Shared data directory. The default is '/usr/local/share' but
you can change the value using configure script.
Htags lookup templete files in the 'gtags' directory
in this data directory.
@item @code{htags_options}(string)
Default options for htags. This value is inserted into
the head of arguments.
@item @code{xhtml_version}(1.0|1.1)
XHTML version. 1.0 and 1.1 are acceptable. The default is 1.0.
@item @code{body_begin}(string)
Begin tag for body. The default is '<body>'.
@item @code{body_end}(string)
End tag for body. The default is '</body>'.
@item @code{table_begin}(string)
Begin tag for table. The default is '<table>'.
@item @code{table_end}(string)
End tag for table. The default is '</table>'.
@item @code{title_begin}(string)
Begin tag for Title. The default is '<h1><font color=#cc0000>'.
@item @code{title_end}(string)
End tag for Title. The default is '</font></h1>'.
@item @code{comment_begin}(string)
Begin tag for comments. The default is '<i><font color=green>'.
@item @code{comment_end}(string)
End tag for comments. The default is '</font></i>'.
@item @code{dynamic}(bool)
Generate object list dynamically.
@item @code{sharp_begin}(string)
Begin tag for 'define'. The default is '<font color=darkred>'.
@item @code{sharp_end}(string)
End tag for 'define'. The default is '</font>'.
@item @code{brace_begin}(string)
Begin tag for brace. The default is '<font color=blue>'.
@item @code{brace_end}(string)
End tag for brace. The default is '</font>'.
@item @code{reserved_begin}(string)
Begin tag for reserved word. The default is '<b>'.
@item @code{reserved_end}(string)
End tag for reserved word. The default is '</b>'.
@item @code{position_begin}(string)
Begin tag for posiotion mark. The default is '<font color=gray>'.
@item @code{position_end}(string)
End tag for posiotion mark. The default is '</font>'.
@item @code{colorize_warned_line}(boolean)
Colorize warned line using @code{warned_line_begin} and @code{warned_line_end}.
The default is false.
@item @code{warned_line_begin}(string)
Begin tag for line which htags warned. The default is '<span style="background-color:yellow">'.
@item @code{warned_line_end}(string)
End tag for line which htags warned. The default is '</span>'.
@item @code{hr}(string)
Horizontal rules. The default is '<hr>'.
@item @code{ncol}(number)
Columns of line number. The default is 4.
@item @code{tabs}(number)
Tab stop. The default is 8.
@item @code{full_path}(boolean)
List file names with full path in file index.
By default, list just the last component of a path.
@item @code{table_list}(boolean)
List tags using table tag. The default is false.
@item @code{normal_suffix}(string)
Suffix for normal html file. The default is 'html'.
@item @code{no_map_file}(boolean)
Doesn't generate @file{MAP} file. The default is false.
@item @code{gzipped_suffix}(string)
Suffix for compressed html file. The default is 'ghtml'.
@item @code{script_alias}(string)
Script alias for safe cgi script (@samp{-S}).
@item @code{show_position}(boolean)
Show position per function definition. The default is false.
@item @code{symbol}(boolean)
Make anchors not only for functions but also other symbols.
@file{GSYMS} tag file needed.
@item @code{definition_header}(no|before|right|after)
Position of link header. The default is 'no'.
@item @code{other_files}(boolean)
File index includes not only source files but also other files. The default is false.
@item @code{enable_grep}(boolean)
Enable grep search using CGI program. The default is false.
When this function is enabled, you cannot move hypertext from source directory.
@item @code{enable_idutils}(boolean)
Enable id-utils search using CGI program. The default is false.
When this function is enabled, you cannot move hypertext from source directory.
@item @code{include_file_suffixes}(comma separated list)
Suffixes of include file. The default is 'h,hxx,hpp,H,inc.php'.
@item @code{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'.
@item @code{copy_files}(boolean)
Copy files instead of linking.
When the @samp{-f} option is used, htags make links
of tag files in @file{cgi-bin} directory by default.
@end table
@unnumberedsubsec DIAGNOSTICS
Htags exits with a non 0 value if an error occurred, 0 otherwise.
@unnumberedsubsec MESSAGE FORMAT
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.
@unnumberedsubsec SEE ALSO
gtags-parser(1),
global(1),
gtags(1).
GNU GLOBAL source code tag system@*
(http://www.gnu.org/software/global/).
@unnumberedsubsec BUG
Generated hypertext is VERY LARGE.
In advance, check the space of your disk.
PHP supprt is far from complete.
@unnumberedsubsec AUTHOR
Tama Communications Corporation.
@unnumberedsubsec HISTORY
The htags command appeared in FreeBSD 2.2.2.
|
