summaryrefslogtreecommitdiffstats
path: root/doc/extsearch.doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc/extsearch.doc')
-rw-r--r--doc/extsearch.doc99
1 files changed, 43 insertions, 56 deletions
diff --git a/doc/extsearch.doc b/doc/extsearch.doc
index a86d1db..d69b36e 100644
--- a/doc/extsearch.doc
+++ b/doc/extsearch.doc
@@ -1,6 +1,6 @@
/******************************************************************************
*
- * Copyright (C) 1997-2012 by Dimitri van Heesch.
+ * Copyright (C) 1997-2013 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
@@ -14,6 +14,8 @@
*/
/*! \page extsearch External Indexing and Searching
+[TOC]
+
\section extsearch_intro Introduction
With release 1.8.3, doxygen provides the ability to search through HTML using
@@ -34,26 +36,9 @@ engine, doxygen provides an example tool for each action: `doxyindexer`
for indexing the data and `doxysearch.cgi` for searching through the index.
The data flow is shown in the following diagram:
-\dot
-digraph Flow {
- edge [fontname="helvetica",fontsize="10pt"];
- node [shape=ellipse,fontname="helvetica",fontsize="10pt"];
- doxygen;
- doxyindexer;
- doxysearch [label="doxysearch.cgi"];
- browser [label="HTML page\nin browser"];
- node [shape=note];
- searchdata [label="searchdata.xml"];
- searchindex [label="doxysearch.db"];
-
- doxygen -> searchdata [label=" writes"];
- searchdata -> doxyindexer [label=" reads"];
- doxyindexer -> searchindex [label=" writes"];
- searchindex -> doxysearch [label=" reads"];
- doxysearch -> browser [label=" get results "];
- browser -> doxysearch [label=" query "];
-}
-\enddot
+
+\image html extsearch_flow.png "External Search Data Flow"
+\image latex extsearch_flow.eps "External Search Data Flow" height=10cm
- `doxygen` produces the raw search data
- `doxyindexer` indexes the data into a search database `doxysearch.db`
@@ -135,47 +120,49 @@ Now you should be enable to search for words and symbols from the HTML output.
\subsection extsearch_multi Multi project index
-In case you have two doxygen projects A and B where B depends on A via a
-tag file, i.e. the configuration of project A says:
-
- GENERATE_TAGFILES = A.tag
-
-and the configuration of project B has its dependency on A configured as
-follows:
-
- TAGFILES = ../project_A/A.tag=../../project_A/html
-
-then it may be desirable to allow searching for words in both projects.
+In case you have more than one doxygen project and these projects are related,
+it may be desirable to allow searching for words in all projects from within
+the documentation of any of the projects.
To make this possible all that is needed is to combine the search data
-for both projects into one index, i.e. run
+for all projects into a single index, e.g. for two projects A and B for which the
+searchdata.xml is generated in directories project_A and project_B run:
doxyindexer project_A/searchdata.xml project_B/searchdata.xml
and then copy the resulting `doxysearch.db` to the directory where also
-`doxysearch.cgi` used by project B is located.
-
-In case you also want to link to search results in project B
-from the search page of project A (or in general
-between two projects that are otherwise unrelated),
-you need to give some additional information in order for doxygen to make
-the right links. This is what the
-\ref cfg_extra_search_mappings "EXTRA_SEARCH_MAPPINGS" option is for.
-
-Each project needs to have a tag file defined, i.e. in the above example
-involving project A and B, also project B should define a tag file:
-
- GENERATE_TAGFILES = B.tag
-
-then project A can define the mapping as follows:
-
- EXTRA_SEARCH_MAPPINGS = B.tag=../../project_B/html
-
-with this addition, projects A and B can share the same search database.
-
-@note The mapping defined by `EXTRA_SEARCH_MAPPINGS` is treated as an
-extension of the mappings already defined by `TAGFILES`. In case the same
-tag file is mentioned in both options, the one in `TAGFILES` is used.
+`doxysearch.cgi` is located.
+
+The `searchdata.xml` file doesn't contain any absolute paths or links,
+so how can the search results from multiple projects be linked back to the right documentation set?
+This is where the `EXTERNAL_SEARCH_ID` and `EXTRA_SEARCH_MAPPINGS` options come into play.
+
+To be able to identify the different projects, one needs to
+set a unique ID using \ref cfg_external_search_id "EXTERNAL_SEARCH_ID"
+for each project.
+
+To link the search results to the right project, you need to define a
+mapping per project using the \ref cfg_extra_search_mappings "EXTRA_SEARCH_MAPPINGS" tag.
+With this option to can define the mapping from IDs of other projects to the
+(relative) location of documentation of those projects.
+
+So for projects A and B the relevant part of the configuration file
+could look as follows:
+
+ project_A/Doxyfile
+ ------------------
+ EXTERNAL_SEARCH_ID = A
+ EXTRA_SEARCH_MAPPINGS = B=../../project_B/html
+
+for project A and for project B
+
+ project_B/Doxyfile
+ ------------------
+ EXTERNAL_SEARCH_ID = B
+ EXTRA_SEARCH_MAPPINGS = A=../../project_A/html
+
+with these settings, projects A and B can share the same search database,
+and the search results will link to the right documentation set.
\section extsearch_update Updating the index