From 440e8d4efa6a51a25dda4636a31a7bf9932fada4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sebastian=20H=C3=B6ffner?= <info@sebastian-hoeffner.de>
Date: Wed, 4 Oct 2017 15:52:12 +0200
Subject: [PATCH] Configuring Doxygen to generate a tag file.

Additionally adds a tutorial on how to use the tag file in other
projects to link back to the OpenCV documentation.

The tutorial is also the only place which links to the tag file as of
now.

For more information on tag files and external documentation, check
https://www.stack.nl/~dimitri/doxygen/manual/external.html
---
 doc/Doxyfile.in                               |  2 +-
 .../tutorial_cross_referencing.markdown       | 61 +++++++++++++++++++
 .../table_of_content_introduction.markdown    |  8 +++
 3 files changed, 70 insertions(+), 1 deletion(-)
 create mode 100644 doc/tutorials/introduction/cross_referencing/tutorial_cross_referencing.markdown

diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index 1276a6b9c8..382255468f 100644
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -255,7 +255,7 @@ PREDEFINED             = __cplusplus=1 \
 EXPAND_AS_DEFINED      =
 SKIP_FUNCTION_MACROS   = YES
 TAGFILES               =
-GENERATE_TAGFILE       =
+GENERATE_TAGFILE       = @CMAKE_DOXYGEN_OUTPUT_PATH@/html/opencv.tag
 ALLEXTERNALS           = NO
 EXTERNAL_GROUPS        = YES
 EXTERNAL_PAGES         = YES
diff --git a/doc/tutorials/introduction/cross_referencing/tutorial_cross_referencing.markdown b/doc/tutorials/introduction/cross_referencing/tutorial_cross_referencing.markdown
new file mode 100644
index 0000000000..acc788d84e
--- /dev/null
+++ b/doc/tutorials/introduction/cross_referencing/tutorial_cross_referencing.markdown
@@ -0,0 +1,61 @@
+Cross referencing OpenCV from other Doxygen projects {#tutorial_cross_referencing}
+====================================================
+
+Cross referencing OpenCV
+------------------------
+
+[Doxygen](https://www.stack.nl/~dimitri/doxygen/) is a tool to generate
+documentations like the OpenCV documentation you are reading right now.
+It is used by a variety of software projects and if you happen to use it
+to generate your own documentation, and you are using OpenCV inside your
+project, this short tutorial is for you.
+
+Imagine this warning inside your documentation code:
+
+@code
+/**
+ * @warning This functions returns a cv::Mat.
+ */
+@endcode
+
+Inside your generated documentation this warning will look roughly like this:
+
+@warning This functions returns a %cv::Mat.
+
+While inside the OpenCV documentation the `%cv::Mat` is rendered as a link:
+
+@warning This functions returns a cv::Mat.
+
+To generate links to the OpenCV documentation inside your project, you only
+have to perform two small steps. First download the file
+[opencv.tag](opencv.tag) (right-click and choose "save as...") and place it
+somewhere in your project directory, for example as
+`docs/doxygen-tags/opencv.tag`.
+
+Open your Doxyfile using your favorite text editor and search for the key
+`TAGFILES`. Change it as follows:
+
+@code
+TAGFILES = ./docs/doxygen-tags/opencv.tag=http://docs.opencv.org/3.3.0
+@endcode
+
+If you had other definitions already, you can append the line using a `\`:
+
+@code
+TAGFILES = ./docs/doxygen-tags/libstdc++.tag=https://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen \
+           ./docs/doxygen-tags/opencv.tag=http://docs.opencv.org/3.3.0
+@endcode
+
+Doxygen can now use the information from the tag file to link to the OpenCV
+documentation. Rebuild your documentation right now!
+
+@note To allow others to also use a *.tag file to link to your documentation,
+set `GENERATE_TAGFILE = html/your_project.tag`. Your documentation will now
+contain a `your_project.tag` file in its root directory.
+
+
+References
+----------
+
+- [Doxygen: Linking to external documentation](https://www.stack.nl/~dimitri/doxygen/manual/external.html)
+- [opencv.tag](opencv.tag)
diff --git a/doc/tutorials/introduction/table_of_content_introduction.markdown b/doc/tutorials/introduction/table_of_content_introduction.markdown
index 37820a8e1b..ebd2793039 100644
--- a/doc/tutorials/introduction/table_of_content_introduction.markdown
+++ b/doc/tutorials/introduction/table_of_content_introduction.markdown
@@ -171,3 +171,11 @@ Additionally you can find very basic sample source code to introduce you to the
     _Author:_ Maksim Shabunin
 
     This document describes some aspects of 2.4 -> 3.0 transition process.
+
+-   @subpage tutorial_cross_referencing
+
+    _Compatibility:_ \> OpenCV 3.3.0
+
+    _Author:_ Sebastian Höffner
+
+    This document outlines how to create cross references to the OpenCV documentation from other Doxygen projects.