diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Doxyfile | 2 | ||||
| -rw-r--r-- | doc/commands.doc | 43 | ||||
| -rw-r--r-- | doc/config.doc | 128 | ||||
| -rw-r--r-- | doc/doxygen_manual.css | 2 | ||||
| -rw-r--r-- | doc/doxygen_manual.tex | 1 | ||||
| -rw-r--r-- | doc/doxyindexer.1 | 17 | ||||
| -rw-r--r-- | doc/doxysearch.1 | 11 | ||||
| -rw-r--r-- | doc/extsearch.doc | 320 | ||||
| -rw-r--r-- | doc/faq.doc | 2 | ||||
| -rw-r--r-- | doc/index.doc | 1 | ||||
| -rw-r--r-- | doc/install.doc | 14 | ||||
| -rw-r--r-- | doc/language.doc | 2 | ||||
| -rw-r--r-- | doc/searching.doc | 44 | ||||
| -rw-r--r-- | doc/translator_report.txt | 2 |
14 files changed, 499 insertions, 90 deletions
diff --git a/doc/Doxyfile b/doc/Doxyfile index 1b0a311..50cede6 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -35,7 +35,7 @@ CASE_SENSE_NAMES = NO IMAGE_PATH = . INPUT = index.doc install.doc starting.doc docblocks.doc markdown.doc \ lists.doc grouping.doc formulas.doc diagrams.doc preprocessing.doc \ - autolink.doc output.doc searching.doc customize.doc custcmd.doc \ + autolink.doc output.doc searching.doc extsearch.doc customize.doc custcmd.doc \ external.doc faq.doc trouble.doc features.doc \ doxygen_usage.doc doxywizard_usage.doc \ config.doc commands.doc htmlcmds.doc xmlcmds.doc language.doc \ diff --git a/doc/commands.doc b/doc/commands.doc index b19e38f..03d6d3c 100644 --- a/doc/commands.doc +++ b/doc/commands.doc @@ -55,7 +55,6 @@ documentation: \refitem cmdclass \\class \refitem cmdcode \\code \refitem cmdcond \\cond -\refitem cmdcondnot \\condnot \refitem cmdcopybrief \\copybrief \refitem cmdcopydetails \\copydetails \refitem cmdcopydoc \\copydoc @@ -1083,8 +1082,10 @@ Section indicators The section between \\cond and \\endcond commands can be included by adding its section label to the \ref cfg_enabled_sections "ENABLED_SECTIONS" configuration option. If the section label is omitted, the section will - be excluded from processing unconditionally. The section label can be a logical expression - build of section names, round brackets, && (AND), || (OR) and ! (NOT). + be excluded from processing unconditionally. The section label can be a + logical expression build of section lavels, round brackets, && (AND), || (OR) and ! (NOT). + If you use an expression you need to wrap it in round brackets, i.e + <tt>\\cond (!LABEL1 && LABEL2)</tt>. For conditional sections within a comment block one should use a \ref cmdif "\\if" ... \ref cmdendif "\\endif" block. @@ -1137,30 +1138,7 @@ class Implementation : public Intf The output will be different depending on whether or not \c ENABLED_SECTIONS contains \c TEST, or \c DEV - \sa section \ref cmdcondnot "\\condnot" and section \ref cmdendcond "\\endcond". - -<hr> -\section cmdcondnot \\condnot [(section-label)] - - \addindex \\condnot - Starts a conditional section that ends with a corresponding - \ref cmdendcond "\\endcond" command, which is typically found in - another comment block. The main purpose of this pair of - commands is to (conditionally) exclude part of a file from processing - (in older version of doxygen this could only be achieved using C preprocessor commands). - - The section between \\condnot and \\endcond commands can be excluded by - adding its section label to the \ref cfg_enabled_sections "ENABLED_SECTIONS" - configuration option. The section label can be a logical expression - build of section names, round brackets, && (AND), || (OR) and ! (NOT). - - For conditional sections within a comment block one should - use a \ref cmdif "\\if" ... \ref cmdendif "\\endif" block. - - Conditional sections can be nested. In this case a nested section will only - be shown if it and its containing section are included. - - \sa section \ref cmdcond "\\cond" and section \ref cmdendcond "\\endcond". + \sa section \ref cmdendcond "\\endcond". <hr> \section cmdcopyright \\copyright { copyright description } @@ -1233,9 +1211,9 @@ contains \c TEST, or \c DEV \section cmdendcond \\endcond \addindex \\endcond - Ends a conditional section that was started by \ref cmdcond "\\cond" or \ref cmdcondnot "\\condnot". + Ends a conditional section that was started by \ref cmdcond "\\cond". - \sa section \ref cmdcond "\\cond" and section \ref cmdcondnot "\\condnot". + \sa section \ref cmdcond "\\cond". <hr> \section cmdendif \\endif @@ -1269,8 +1247,13 @@ contains \c TEST, or \c DEV with a matching \c \\endif command. A conditional section is disabled by default. To enable it you must put the section-label after the \ref cfg_enabled_sections "ENABLED_SECTIONS" - tag in the configuration file. The section label can be a logical expression + tag in the configuration file. + + The section label can be a logical expression build of section names, round brackets, && (AND), || (OR) and ! (NOT). + If you use an expression you need to wrap it in round brackets, i.e + <tt>\\cond (!LABEL1 && LABEL2)</tt>. + Conditional blocks can be nested. A nested section is only enabled if all enclosing sections are enabled as well. diff --git a/doc/config.doc b/doc/config.doc index 64456c7..2fdabb0 100644 --- a/doc/config.doc +++ b/doc/config.doc @@ -114,7 +114,9 @@ followed by the descriptions of the tags grouped by category. \refitem cfg_ext_links_in_window EXT_LINKS_IN_WINDOW \refitem cfg_extension_mapping EXTENSION_MAPPING \refitem cfg_external_groups EXTERNAL_GROUPS +\refitem cfg_external_search EXTERNAL_SEARCH \refitem cfg_extra_packages EXTRA_PACKAGES +\refitem cfg_extra_search_mappings EXTRA_SEARCH_MAPPINGS \refitem cfg_extract_all EXTRACT_ALL \refitem cfg_extract_anon_nspaces EXTRACT_ANON_NSPACES \refitem cfg_extract_local_classes EXTRACT_LOCAL_CLASSES @@ -251,7 +253,9 @@ followed by the descriptions of the tags grouped by category. \refitem cfg_rtf_output RTF_OUTPUT \refitem cfg_rtf_stylesheet_file RTF_STYLESHEET_FILE \refitem cfg_search_includes SEARCH_INCLUDES +\refitem cfg_searchdata_file SEARCHDATA_FILE \refitem cfg_searchengine SEARCHENGINE +\refitem cfg_searchengine_url SEARCHENGINE_URL \refitem cfg_separate_member_pages SEPARATE_MEMBER_PAGES \refitem cfg_server_based_search SERVER_BASED_SEARCH \refitem cfg_short_names SHORT_NAMES @@ -503,7 +507,7 @@ followed by the descriptions of the tags grouped by category. <dt>\c SIP_SUPPORT <dd> \addindex OPTIMIZE_OUTPUT_SIP Set the SIP_SUPPORT tag to YES if your project consists - of <a href="http://www.riverbankcomputing.co.uk/sip/">sip</a> sources only. + of <a href="http://www.riverbankcomputing.co.uk/software/sip/intro">sip</a> sources only. Doxygen will parse them like normal C++ but will assume all classes use public instead of private inheritance when no explicit protection keyword is present. @@ -1762,43 +1766,6 @@ The GENERATE_PUBLISHER_NAME tag identifies the documentation publisher. the directory name containing the HTML and XML files should also have this name. Each documentation set should have its own identifier. -\anchor cfg_searchengine -<dt>\c SEARCHENGINE <dd> - \addindex SEARCHENGINE - - When the \c SEARCHENGINE tag is enabled doxygen will generate a search box - for the HTML output. The underlying search engine uses javascript - and DHTML and should work on any modern browser. Note that when using - HTML help (\ref cfg_generate_htmlhelp "GENERATE_HTMLHELP"), - Qt help (\ref cfg_generate_qhp "GENERATE_QHP"), or docsets - (\ref cfg_generate_docset "GENERATE_DOCSET") there is already a search - function so this one should typically be disabled. For large projects - the javascript based search engine can be slow, then enabling - \ref cfg_server_based_search "SERVER_BASED_SEARCH" may provide a - better solution. - - It is possible to search using the keyboard; - to jump to the search box use access key + S (what the access key is - depends on the OS and browser, but it is typically CTRL, ALT/option, or both). - Inside the search box use the cursor down key to jump into the search - results window, the results can be navigated using the cursor keys. - Press Enter to select an item or escape to cancel the search. The - filter options can be selected when the cursor is inside the search box - by pressing Shift+cursor down. Also here use the cursor keys to - select a filter and enter or escape to activate or cancel the filter option. - -\anchor cfg_server_based_search -<dt>\c SERVER_BASED_SEARCH <dd> - \addindex SERVER_BASED_SEARCH - -When the SERVER_BASED_SEARCH tag is enabled the search engine will be -implemented using a PHP enabled web server instead of at the web client -using Javascript. Doxygen will generate the search PHP script and index -file to put on the web server. The advantage of the server -based approach is that it scales better to large projects and also allows -full text search. The disadvantages are that it is more difficult to setup -and does not have live searching capabilities. - \anchor cfg_disable_index <dt>\c DISABLE_INDEX <dd> \addindex DISABLE_INDEX @@ -1907,6 +1874,91 @@ for more details. \verbatim MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols \endverbatim + +\anchor cfg_searchengine +<dt>\c SEARCHENGINE <dd> + \addindex SEARCHENGINE + + When the \c SEARCHENGINE tag is enabled doxygen will generate a search box + for the HTML output. The underlying search engine uses javascript + and DHTML and should work on any modern browser. Note that when using + HTML help (\ref cfg_generate_htmlhelp "GENERATE_HTMLHELP"), + Qt help (\ref cfg_generate_qhp "GENERATE_QHP"), or docsets + (\ref cfg_generate_docset "GENERATE_DOCSET") there is already a search + function so this one should typically be disabled. For large projects + the javascript based search engine can be slow, then enabling + \ref cfg_server_based_search "SERVER_BASED_SEARCH" may provide a + better solution. + + It is possible to search using the keyboard; + to jump to the search box use access key + S (what the access key is + depends on the OS and browser, but it is typically CTRL, ALT/option, or both). + Inside the search box use the cursor down key to jump into the search + results window, the results can be navigated using the cursor keys. + Press Enter to select an item or escape to cancel the search. The + filter options can be selected when the cursor is inside the search box + by pressing Shift+cursor down. Also here use the cursor keys to + select a filter and enter or escape to activate or cancel the filter option. + +\anchor cfg_server_based_search +<dt>\c SERVER_BASED_SEARCH <dd> + \addindex SERVER_BASED_SEARCH + +When the \c SERVER_BASED_SEARCH tag is enabled the search engine will be +implemented using a web server instead of a web client using Javascript. + +There are two flavours of web server based searching depending on the +\ref cfg_external_search "EXTERNAL_SEARCH" setting. When disabled, +doxygen will generate a PHP script for searching and an index file used +by the script. When \ref cfg_external_search "EXTERNAL_SEARCH" is +enabled the indexing and searching needs to be provided by external tools. +See \ref extsearch for details. + +\anchor cfg_external_search +<dt>\c EXTERNAL_SEARCH <dd> + \addindex EXTERNAL_SEARCH + +When \c EXTERNAL_SEARCH is enabled doxygen will no longer generate the PHP +script for searching. Instead the search results are written to an XML file +which needs to be processed by an external indexer. Doxygen will invoke an +external search engine pointed to by the +\ref cfg_searchengine_url "SEARCHENGINE_URL" option to obtain +the search results. See the section \ref extsearch for details. + +\anchor cfg_searchengine_url +<dt>\c SEARCHENGINE_URL <dd> + \addindex SEARCHENGINE_URL + +The \c SEARCHENGINE_URL should point to a search engine hosted by a web server +which will returned the search results when \ref cfg_external_search "EXTERNAL_SEARCH" +is enabled. See the section \ref extsearch for details. + +\anchor cfg_searchdata_file +<dt>\c SEARCHDATA_FILE <dd> + \addindex SEARCHDATA_FILE + +When \ref cfg_server_based_search "SERVER_BASED_SEARCH" and +\ref cfg_external_search "EXTERNAL_SEARCH" are both enabled the unindexed +search data is written to a file for indexing by an external tool. With the +\c SEARCHDATA_FILE tag the name of this file can be specified. +The default is searchdata.xml. + +\anchor cfg_extra_search_mappings +<dt>\c EXTRA_SEARCH_MAPPINGS <dd> + \addindex EXTRA_SEARCH_MAPPINGS + +The \c EXTRA_SEARCH_MAPPINGS tag can be used to enable searching through other +doxygen projects that are not otherwise connected via tags files, but are +all added to the same search index. Each project needs to have a tag file set +via \ref cfg_generate_tagfile "GENERATE_TAGFILE". The search mapping then +maps the name of tag file to a relative location where the documentation +can be found, similar to the \ref cfg_tagfiles "TAGFILES" option but without +actually processing the tag file. The format is: + +\verbatim +EXTRA_SEARCH_MAPPINGS = tagname1=loc1 tagname2=loc2 ... +\endverbatim + </dl> \section latex_output LaTeX related options diff --git a/doc/doxygen_manual.css b/doc/doxygen_manual.css index 644e4d7..45395b4 100644 --- a/doc/doxygen_manual.css +++ b/doc/doxygen_manual.css @@ -871,7 +871,7 @@ div.header div.headertitle { - padding: 5px 5px 5px 7px; + padding: 5px 5px 5px 0px; } dl diff --git a/doc/doxygen_manual.tex b/doc/doxygen_manual.tex index 1c9ad2a..cd9a544 100644 --- a/doc/doxygen_manual.tex +++ b/doc/doxygen_manual.tex @@ -90,6 +90,7 @@ Written by Dimitri van Heesch\\[2ex] \chapter{Automatic link generation}\label{autolink}\hypertarget{autolink}{}\input{autolink} \chapter{Output Formats}\label{output}\hypertarget{output}{}\input{output} \chapter{Searching}\label{searching}\hypertarget{searching}{}\input{searching} +\chapter{External Indexing and Searching}\label{extsearch}\hypertarget{extsearch}{}\input{extsearch} \chapter{Customizing the Output}\label{customize}\hypertarget{customize}{}\input{customize} \chapter{Custom Commands}\label{custcmd}\hypertarget{custcmd}{}\input{custcmd} \chapter{Link to external documentation}\label{external}\hypertarget{external}{}\input{external} diff --git a/doc/doxyindexer.1 b/doc/doxyindexer.1 new file mode 100644 index 0000000..7b7a298 --- /dev/null +++ b/doc/doxyindexer.1 @@ -0,0 +1,17 @@ +.TH DOXYINDEXER "1" "DATE" "doxyindexer VERSION" "User Commands" +.SH NAME +doxyindexer \- creates a search index from raw search data +.SH SYNOPSIS +.B doxyindexer +[\fI-o output_dir\fR] \fIsearchdata.xml \fR[\fIsearchdata2.xml\fR...] ] +.SH DESCRIPTION +Generates a search index called \fBdoxysearch.db\fR from one or more +search data files produced by doxygen. Use +doxysearch.cgi as a CGI program to search the data indexed by doxyindexer. +.SH OPTIONS +.TP +\fB\-o\fR <output_dir> +The directory where to write the doxysearch.db to. +If omitted the current directory is used. +.SH SEE ALSO +doxygen(1), doxysearch(1), doxywizard(1). diff --git a/doc/doxysearch.1 b/doc/doxysearch.1 new file mode 100644 index 0000000..da9ae05 --- /dev/null +++ b/doc/doxysearch.1 @@ -0,0 +1,11 @@ +.TH DOXYSEARCH "1" "DATE" "doxysearch.cgi VERSION" "User Commands" +.SH NAME +doxysearch.cgi \- search engine used for searching in doxygen documentation. +.SH SYNOPSIS +.B doxyindexer.cgi +.SH DESCRIPTION +CGI binary that is used by doxygen generated HTML output to search for words. +The tool uses the search index called \fBdoxysearch.db\fR produced by +doxyindexer. +.SH SEE ALSO +doxygen(1), doxysearch(1), doxywizard(1). diff --git a/doc/extsearch.doc b/doc/extsearch.doc new file mode 100644 index 0000000..a86d1db --- /dev/null +++ b/doc/extsearch.doc @@ -0,0 +1,320 @@ +/****************************************************************************** + * + * Copyright (C) 1997-2012 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 extsearch External Indexing and Searching + +\section extsearch_intro Introduction + +With release 1.8.3, doxygen provides the ability to search through HTML using +an external indexing tool and search engine. +This has several advantages: +- For large projects it can have significant performance advantages over + doxygen's built-in search engine, as doxygen uses a rather simple indexing + algorithm. +- It allows combining the search data of multiple projects into one index, + allowing a global search across multiple doxygen projects. +- It allows adding additional data to the search index, i.e. other web pages + not produced by doxygen. +- The search engine needs to run on a web server, but clients can still browse + the web pages locally. + +To avoid that everyone has to start writing their own indexer and search +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 + +- `doxygen` produces the raw search data +- `doxyindexer` indexes the data into a search database `doxysearch.db` +- when a user performs a search from a doxygen generated HTML page, + the CGI binary `doxysearch.cgi` will be invoked. +- the `doxysearch.cgi` tool will perform a query on the database and return + the results. +- The browser will show the search results. + +\section extsearch_config Configuring + +The first step is to make the search engine available via a web server. +If you use `doxysearch.cgi` this means making the +<a href="http://en.wikipedia.org/wiki/Common_Gateway_Interface">CGI</a> binary +available from the web server (i.e. be able to run it from a +browser via an URL starting with http:) + +How to setup a web server is outside the scope of this document, +but if you for instance have Apache installed, you could simply copy the +`doxysearch.cgi` file from doxygen's `bin` dir to the `cgi-bin` of the +Apache web server. Read the <a href="http://httpd.apache.org/docs/2.2/howto/cgi.html">apache documentation</a> for details. + +To test if `doxysearch.cgi` is accessible start your web browser and +point to URL to the binary and add `?test` at the end + + http://yoursite.com/path/to/cgi/doxysearch.cgi?test + +You should get the following message: + + Test failed: cannot find search index doxysearch.db + +If you use Internet Explorer you may be prompted to download a file, +which will then contain this message. + +Since we didn't create or install a doxysearch.db it is ok for the test to +fail for this reason. How to correct this is discussed in the next section. + +Before continuing with the next section add the above +URL (without the `?test` part) to the `SEARCHENGINE_URL` tag in +doxygen's configuration file: + + SEARCHENGINE_URL = http://yoursite.com/path/to/cgi/doxysearch.cgi + +\subsection extsearch_single Single project index + +To use the external search option, make sure the following options are enabled +in doxygen's configuration file: + + SEARCHENGINE = YES + SERVER_BASED_SEARCH = YES + EXTERNAL_SEARCH = YES + +This will make doxygen generate a file called `searchdata.xml` in the output +directory (configured with \ref cfg_output_directory "OUTPUT_DIRECTORY"). +You can change the file name (and location) with the +\ref cfg_searchdata_file "SEARCHDATA_FILE" option. + +The next step is to put the raw search data into an index for efficient +searching. You can use `doxyindexer` for this. Simply run it from the command +line: + + doxyindexer searchdata.xml + +This will create a directory called `doxysearch.db` with some files in it. +By default the directory will be created at the location from which doxyindexer +was started, but you can change the directory using the `-o` option. + +Copy the `doxysearch.db` directory to the same directory as where +the `doxysearch.cgi` is located and rerun the browser test by pointing +the browser to + + http://yoursite.com/path/to/cgi/doxysearch.cgi?test + +You should now get the following message: + + Test successful. + +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. + +To make this possible all that is needed is to combine the search data +for both projects into one index, i.e. 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. + +\section extsearch_update Updating the index + +When you modify the source code, you should re-run doxygen to get up to date +documentation again. When using external searching you also need to update the +search index by re-running `doxyindexer`. You could wrap the call to doxygen +and doxyindexer together in a script to make this process easier. + +\section extsearch_api Programming interface + +Previous sections have assumed you use the tools `doxyindexer` +and `doxysearch.cgi` to do the indexing and searching, but you could also +write your own index and search tools if you like. + +For this 3 interfaces are important +- The format of the input for the index tool. +- The format of the input for the search engine. +- The format of the output of search engine. + +The next subsections describe these interfaces in more detail. + +\subsection extsearch_api_index Indexer input format + +The search data produced by doxygen follows the +<a href="http://wiki.apache.org/solr/UpdateXmlMessages">Solr XML index message</a> +format. + +The input for the indexer is an XML file, which consists of one `<add>` tag containing +multiple `<doc>` tags, which in turn contain multiple `<field>` tags. + +Here is an example of one doc node, which contains the search data and meta data for +one method: + + <add> + ... + <doc> + <field name="type">function</field> + <field name="name">QXmlReader::setDTDHandler</field> + <field name="args">(QXmlDTDHandler *handler)=0</field> + <field name="tag">qtools.tag</field> + <field name="url">de/df6/class_q_xml_reader.html#a0b24b1fe26a4c32a8032d68ee14d5dba</field> + <field name="keywords">setDTDHandler QXmlReader::setDTDHandler QXmlReader</field> + <field name="text">Sets the DTD handler to handler DTDHandler()</field> + </doc> + ... + </add> + +Each field has a name. The following field names are supported: +- *type*: the type of the search entry; can be one of: source, function, slot, + signal, variable, typedef, enum, enumvalue, property, event, related, + friend, define, file, namespace, group, package, page, dir +- *name*: the name of the search entry; for a method this is the qualified name of the method, + for a class it is the name of the class, etc. +- *args*: the parameter list (in case of functions or methods) +- *tag*: the name of the tag file used for this project. +- *url*: the (relative) URL to the HTML documentation for this entry. +- *keywords*: important words that are representative for the entry. When searching for such + keyword, this entry should get a higher rank in the search results. +- *text*: the documentation associated with the item. Note that only words are present, no markup. + +@note Due to the potentially large size of the XML file, it is recommended to use a +<a href="http://en.wikipedia.org/wiki/Simple_API_for_XML">SAX based parser</a> to process it. + +\subsection extsearch_api_search_in Search URL format + +When the search engine is invoked from a doxygen generated HTML page, a number of parameters are +passed to via the <a href="http://en.wikipedia.org/wiki/Query_string">query string</a>. + +The following fields are passed: +- *q*: the query text as entered by the user +- *n*: the number of search results requested. +- *p*: the number of search page for which to return the results. Each page has *n* values. +- *cb*: the name of the callback function, used for JSON with padding, see the next section. + +From the complete list of search results, the range `[n*p - n*(p+1)-1]` should be returned. + +Here is an example of how a query looks like. + + http://yoursite.com/path/to/cgi/doxysearch.cgi?q=list&n=20&p=1&cb=dummy + +It represents a query for the word 'list' (`q=list`) requesting 20 search results (`n=20`), +starting with the result number 20 (`p=1`) and using callback 'dummy' (`cb=dummy`): + + +@note The values are <a href="http://en.wikipedia.org/wiki/Percent-encoding">URL encoded</a> so they +have to be decoded before they can be used. + +\subsection extsearch_api_search_out Search results format + +When invoking the search engine as shown in the previous subsection, it should reply with +the results. The format of the reply is +<a href="http://en.wikipedia.org/wiki/JSONP">JSON with padding</a>, which is basically +a javascript struct wrapped in a function call. The name of function should be the name of +the callback (as passed with the *cb* field in the query). + +With the example query as shown the previous subsection the main structure of the reply should +look as follows: + + dummy({ + "hits":179, + "first":20, + "count":20, + "page":1, + "pages":9, + "query": "list", + "items":[ + ... + ]}) + +The fields have the following meaning: +- *hits*: the total number of search results (could be more than was requested). +- *first*: the index of first result returned: \f$\min(n*p,\mbox{\em hits})\f$. +- *count*: the actual number of results returned: \f$\min(n,\mbox{\em hits}-\mbox{\em first})\f$ +- *page*: the page number of the result: \f$p\f$ +- *pages*: the total number of pages: \f$\lceil\frac{\mbox{\em hits}}{n}\rceil\f$. +- *items*: an array containing the search data per result. + +Here is an example of how the element of the *items* array should look like: + + {"type": "function", + "name": "QDir::entryInfoList(const QString &nameFilter, int filterSpec=DefaultFilter, int sortSpec=DefaultSort) const", + "tag": "qtools.tag", + "url": "d5/d8d/class_q_dir.html#a9439ea6b331957f38dbad981c4d050ef", + "fragments":[ + "Returns a <span class=\"hl\">list</span> of QFileInfo objects for all files and directories...", + "... pointer to a QFileInfoList The <span class=\"hl\">list</span> is owned by the QDir object...", + "... to keep the entries of the <span class=\"hl\">list</span> after a subsequent call to this..." + ] + }, + +The fields for such an item have the following meaning: +- *type*: the type of the item, as found in the field with name "type" in the raw search data. +- *name*: the name of the item, including the parameter list, as found in the fields with + name "name" and "args" in the raw search data. +- *tag*: the name of the tag file, as found in the field with name "tag" in the raw search data. +- *url*: the name of the (relative) URL to the documentation, as found in the field with name "url" + in the raw search data. +- "fragments": an array with 0 or more fragments of text containing words that have been search for. + These words should be wrapped in `<span class="hl">` and `</span>` tags to highlight them + in the output. + +*/ diff --git a/doc/faq.doc b/doc/faq.doc index cc8a9a4..0475aa7 100644 --- a/doc/faq.doc +++ b/doc/faq.doc @@ -80,7 +80,7 @@ document either the class or namespace. <li><b>How can I make doxygen ignore some code fragment?</b> The new and easiest way is to add one comment block -with a \ref cmdcond "\\cond" or \ref cmdcondnot "\\condnot" command at the start and one comment block +with a \ref cmdcond "\\cond" command at the start and one comment block with a \ref cmdendcond "\\endcond" command at the end of the piece of code that should be ignored. This should be within the same file of course. diff --git a/doc/index.doc b/doc/index.doc index 5207b37..3b2947d 100644 --- a/doc/index.doc +++ b/doc/index.doc @@ -76,6 +76,7 @@ The first part forms a user manual: <li>Section \ref output shows how to generate the various output formats supported by doxygen. <li>Section \ref searching shows various ways to search in the HTML documentation. +<li>Section \ref extsearch shows how use the external search and index tools <li>Section \ref customize explains how you can customize the output generated by doxygen. <li>Section \ref custcmd show how to define and use custom commands in your comments. diff --git a/doc/install.doc b/doc/install.doc index d8a75a2..4622065 100644 --- a/doc/install.doc +++ b/doc/install.doc @@ -338,24 +338,18 @@ compile doxygen. Alternatively, you can compile doxygen <a href="http://en.wikipedia.org/wiki/Cygwin">Cygwin</a> or <a href="http://www.mingw.org/">MinGW</a>. -The next step is to install unxutils (see http://sourceforge.net/projects/unxutils). -This packages contains the tools \c flex and \c bison which are needed during the +The next step is to install bison, flex, and tar +(see http://gnuwin32.sourceforge.net/packages.html). +This packages are needed during the compilation process if you use a CVS snapshot of doxygen (the official source releases come with pre-generated sources). -Download the zip extract it to e.g. <code>c:\\tools\\unxutils</code>. - -Now you need to add/adjust the following environment variables -(via Control Panel/System/Advanced/Environment Variables): -- add <code>c:\\tools\\unxutils\\usr\\local\\wbin;</code> to the start of <code>PATH</code> -- set <code>BISON_SIMPLE</code> to <code>c:\\tools\\unxutils\\usr\\local\\share\\bison.simple</code> Download doxygen's source tarball and put it somewhere (e.g. use <code>c:\\tools</code>) Now start a new command shell and type \verbatim cd c:\tools -gunzip doxygen-x.y.z.src.tar.gz -tar xvf doxygen-x.y.z.src.tar +tar zxvf doxygen-x.y.z.src.tar.gz \endverbatim to unpack the sources. diff --git a/doc/language.doc b/doc/language.doc index b1cdf4e..b0e2ffc 100644 --- a/doc/language.doc +++ b/doc/language.doc @@ -23,7 +23,7 @@ text fragments, generated by doxygen, can be produced in languages other than English (the default). The output language is chosen through the configuration file (with default name and known as Doxyfile). -Currently (version 1.8.1.2), 39 languages +Currently (version 1.8.2), 39 languages are supported (sorted alphabetically): Afrikaans, Arabic, Armenian, Brazilian Portuguese, Catalan, Chinese, Chinese Traditional, Croatian, Czech, Danish, Dutch, English, diff --git a/doc/searching.doc b/doc/searching.doc index b3e4fd9..f80e9f6 100644 --- a/doc/searching.doc +++ b/doc/searching.doc @@ -25,7 +25,7 @@ HTML browsers by default have no search capabilities that work across multiple pages, so either doxygen or external tools need to help to facilitate this feature. -Doxygen has 6 different ways to add searching to the HTML output, each of which +Doxygen has 7 different ways to add searching to the HTML output, each of which has its own advantages and disadvantages: <h2>1. Client side searching</h2> @@ -54,15 +54,45 @@ has its own advantages and disadvantages: To enable this set both \ref cfg_searchengine "SEARCHENGINE" and \ref cfg_server_based_search "SERVER_BASED_SEARCH" to \c YES in the config - file. + file and set \ref cfg_external_search "EXTERNAL_SEARCH" to \c NO. Advantages over the client side search engine are that it provides full - text search and it scales well to large projects. + text search and it scales well to medium side projects. Disadvantages are that it does not work locally (i.e. using a file:// URL) and that it does not provide live search capabilities. -<h2>3. Windows Compiled HTML Help</h2> + @note In the future this option will probably be replaced by the next + search option. + +<h2>3. Server side searching with external indexing</h2> + With release 1.8.3 of doxygen, another server based search option has + been added. With this option doxygen generates the raw data that can be + searched and leaves it up to external tools to do the indexing and + searching, meaning that you could use your own indexer and search engine + of choice. To make life easier doxygen ships with an example indexer + (doxyindexer) and search engine (doxysearch.cgi) based on + the <a href="http://xapian.org/">Xapian</a> open source search engine + library. + + To enable this search method set + \ref cfg_searchengine "SEARCHENGINE", + \ref cfg_server_based_search "SERVER_BASED_SEARCH" and + \ref cfg_external_search "EXTERNAL_SEARCH" all to \c YES. + + See \ref extsearch for configuration details. + + Advantages over option 2 are that this method (potentially) scales to + very large projects. It is also possible to combine multiple doxygen + projects and external data into one search index. + The way the interaction with the search engine is done, makes it + possible to search from local HTML pages. Also the search results have + better ranking and show context information (if available). + + Disadvantages are that is requires a web server that can execute a CGI + binary, and an additional indexing step after running doxygen. + +<h2>4. Windows Compiled HTML Help</h2> If you are running doxygen on Windows, then you can make a compiled HTML Help file (.chm) out of the HTML files produced by doxygen. This is a single file containing all HTML files and it also includes a @@ -83,7 +113,7 @@ has its own advantages and disadvantages: by Microsoft. Although the tool works fine for most people, it can sometimes crash for no apparent reason (how typical). -<h2>4. Mac OS X Doc Sets</h2> +<h2>5. Mac OS X Doc Sets</h2> If you are running doxygen on Mac OS X 10.5 or higher, then you can make a "doc set" out of the HTML files produced by doxygen. A doc set consists of a single directory with a special structure @@ -106,7 +136,7 @@ has its own advantages and disadvantages: Disadvantage is that it only works in combination with Xcode on MacOSX. -<h2>5. Qt Compressed Help</h2> +<h2>6. Qt Compressed Help</h2> If you develop for or want to install the Qt application framework, you will get an application called <a href="http://doc.trolltech.com/4.6/assistant-manual.html">Qt assistant</a>. @@ -129,7 +159,7 @@ has its own advantages and disadvantages: the documentation, which is complicated by the fact that it is not available as a separate package at this moment. -<h2>6. Eclipse Help Plugin</h2> +<h2>7. Eclipse Help Plugin</h2> If you use eclipse, you can embed the documentation generated by doxygen as a help plugin. It will then appear as a topic in the help browser that can be started from "Help contents" in the Help menu. diff --git a/doc/translator_report.txt b/doc/translator_report.txt index b364de4..ad25228 100644 --- a/doc/translator_report.txt +++ b/doc/translator_report.txt @@ -1,4 +1,4 @@ -(1.8.1.2) +(1.8.2) Doxygen supports the following 39 languages (sorted alphabetically): |