\hypertarget{doxytag_usage}{}\section{Doxytag usage}\label{doxytag_usage}
 Doxytag is a small command line based utility. It has two functions: \begin{CompactItemize}
\item 
 Doxytag can generate {\em tag files}. These tag files can be used with \href{doxygen_usage.html}{\tt doxygen}  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 {\em do} have the sources it is better to let {\tt doxygen} generate the tag file by putting the name of the tag file after  \hyperlink{config_cfg_generate_tagfile}{GENERATE\_\-TAGFILE} in the configuration file. \item 
 Doxytag can generate a {\em search index} for the documentation  generated with doxygen or for the Qt documentation. See the documentation of  \href{doxysearch_usage.html}{\tt doxysearch} 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  {\tt doxysearch} can search for words very quickly  (most queries are processed within a few milliseconds on my system.) \end{CompactItemize}
In both cases the input of doxytag consists of a set of HTML files.\begin{Desc}
\item[Important:]\par
 If you use tag files or use a search engine, the links that  are generated by doxygen will contain {\em dummy} links. You have to run  the {\tt installdox} script to change these dummy links into real links. See \hyperlink{installdox_usage}{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 {\tt doxygen},  only {\tt installdox} has to be run.\end{Desc}
\begin{Desc}
\item[Note:]\par
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} the HTML files,  they are not altered in any way.\end{Desc}
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} extension from the current directory. If doxytag is used with the {\tt -t} flag it generates a tag file.\begin{Desc}
\item[Example 1:]\par
 Suppose the file {\tt example.cpp} from the {\tt 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. 

\footnotesize\begin{verbatim}/** A Test class.
 *  More details about this class.
 */

class Test
{
  public:
    /** An example member function.
     *  More details about this function.
     */
    void example();
};

void Test::example() {}

/** \example example_test.cpp
 * This is an example of how to use the Test class.
 * More details about this example.
 */

\end{verbatim}\normalsize 
 Now you can create a tag file from the HTML files in the package by  typing: 

\footnotesize\begin{verbatim}
doxytag -t example.tag example/html
\end{verbatim}\normalsize 
 from the examples directory. Finally you can use this tag file with your own piece of code, such as done in the following example: 

\footnotesize\begin{verbatim}/*! A class that is inherited from the external class Test.
*/

class Tag : public Test
{
  public:
    /*! an overloaded member. */
    void example();
};

\end{verbatim}\normalsize 
 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 \hyperlink{installdox_usage}{Installdox usage} for more information).\end{Desc}
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.

\begin{Desc}
\item[Example 2:]\par
 To generate a tag file of the Qt documentation you can do the following: 

\footnotesize\begin{verbatim}
doxytag -t qt.tag $QTDIR/html
\end{verbatim}\normalsize 
\end{Desc}
A typical example to use doxytag to generate a search index is: 

\footnotesize\begin{verbatim}
doxytag -s search.idx 
\end{verbatim}\normalsize 
\begin{Desc}
\item[Note:]\par
In the current version of doxygen, the search index must be  called {\tt search.idx}.\end{Desc}
