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
|
/******************************************************************************
*
*
*
* Copyright (C) 1997-2002 by Dimitri van Heesch.
*
* Permission to use, copy, modify, and distribute this software and its
* documentation under the terms of the GNU General Public License is hereby
* granted. No representations are made about the suitability of this software
* for any purpose. It is provided "as is" without express or implied warranty.
* See the GNU General Public License for more details.
*
* Documents produced by Doxygen are derivative works derived from the
* input used in their production; they are not affected by this license.
*
*/
/*! \page doxytag_usage Doxytag usage
Doxytag is a small command line based utility.
It has two functions:
<ul>
<li>
Doxytag can generate <em>tag files</em>.
These tag files can be used with <a href="doxygen_usage.html">doxygen</a>
to generate references to external documentation
(i.e. documentation not contained in the input files that are used by
doxygen).
A tag file contains information about files, classes and members
documented in external documentation. Doxytag extracts this information
directly from the HTML files. This has the advantage that you do not need
to have the sources from which the documentation was extracted.
If you \e do have the sources it is better to let \c doxygen generate the
tag file by putting the name of the tag file after
\ref cfg_generate_tagfile "GENERATE_TAGFILE" in
the configuration file.
<li>
Doxytag can generate a <em>search index</em> for the documentation
generated with doxygen or for the Qt documentation. See the documentation of
<a href="doxysearch_usage.html">doxysearch</a> for more information on how
to do this.
A search index contains information about all the words (and all substrings
thereof) that are contained in the documentation.
For each string the index contains the set of documentation blocks that
contain the string and the frequency of occurrence. This way
<code>doxysearch</code> can search for words very quickly
(most queries are processed within a few milliseconds on my system.)
</ul>
In both cases the input of doxytag consists of a set of HTML files.
\par Important:
If you use tag files or use a search engine, the links that
are generated by doxygen will contain \e dummy links. You have to run
the \c installdox script to change these dummy links into real links.
See \ref installdox_usage for more information.
The use of dummy links may seem redundant, but it is really useful,
if you want to move the external documentation to another location.
Then the documentation does not need to be regenerated by \c doxygen,
only \c installdox has to be run.
\par Note:
Because the HTML files are expected to have a certain
structure, only HTML files generated with doxygen or with Qt's class
browser generator can be used. Doxytag only <em>reads</em> the HTML files,
they are not altered in any way.
Doxytag expects a list of all HTML files that form the documentation
or a directory that contains all HTML files. If neither is present doxytag
will read all files with a <tt>.html</tt> extension from the current directory.
If doxytag is used with the <code>-t</code> flag it generates a tag file.
\par Example 1:
Suppose the file \c example.cpp from the \c examples directory that is listed
below is included in some package for which you do not have the sources.
Fortunately, the distributor of the packages included the HTML documentation
that was generated by doxygen in the package.
\verbinclude example.cpp
Now you can create a tag file from the HTML files in the package by
typing:
\verbatim
doxytag -t example.tag example/html
\endverbatim
from the examples directory.
Finally you can use this tag file with your own piece of code, such
as done in the following example:
\verbinclude tag.cpp
Doxygen will now include links to the external package in your own
documentation. Because the tag file does not specify where the
documentation is located, you will have to specify that by running the
installdox script that doxygen generates
(See section \ref installdox_usage for more information).
Note that this is actually a feature because if you (or someone else)
moves the external documentation to a different
directory or URL you can simply run the script again and all links in
the HTML files will be updated.
\htmlonly
Click <a href="$(DOXYGEN_DOCDIR)/examples/tag/html/index.html">here</a>
for the corresponding HTML documentation that is generated by Doxygen using
only the tag file and second piece of code.
\endhtmlonly
\par Example 2:
To generate a tag file of the Qt documentation you can do the following:
\verbatim
doxytag -t qt.tag $QTDIR/html
\endverbatim
A typical example to use doxytag to generate a search index is:
\verbatim
doxytag -s search.idx
\endverbatim
\par Note:
In the current version of doxygen, the search index must be
called \c search.idx.
*/
|
