diff options
Diffstat (limited to 'doc/doxytag_usage.doc')
| -rw-r--r-- | doc/doxytag_usage.doc | 116 |
1 files changed, 116 insertions, 0 deletions
diff --git a/doc/doxytag_usage.doc b/doc/doxytag_usage.doc new file mode 100644 index 0000000..fb966fd --- /dev/null +++ b/doc/doxytag_usage.doc @@ -0,0 +1,116 @@ +/****************************************************************************** + * + * $Id$ + * + * Copyright (C) 1997-1999 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. + * + * All output generated with Doxygen is not covered 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 do have the sources you can also let \c doxygen generate the + tag file by putting the name of the tag file after \c 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 Notice: +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 \ref installdox_usage for more information). + + Notice 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 Notice: +In the current version of doxygen, the search index must be +called \c search.idx. + +*/ |