Improve FindDCMTK.cmake documentation

Also added a troubleshooting section addressing issue #382

Utilities/CMake/FindDCMTK.cmake

@@ -1,9 +1,7 @@
-# adapted version of FindDCMTK, better suited for super-builds
-
 # - find DCMTK libraries and applications
+# The module defines the following variables:
 #
-
-#  DCMTK_INCLUDE_DIRS   - Directories to include to use DCMTK
+#  DCMTK_INCLUDE_DIRS  - Directories to include to use DCMTK
 #  DCMTK_LIBRARIES     - Files to link against to use DCMTK
 #  DCMTK_FOUND         - If false, don't try to use DCMTK
 #  DCMTK_DIR           - (optional) Source directory for DCMTK
@@ -12,7 +10,90 @@
 # directories and compiled libraries if you've just compiled it in the
 # source tree. Just set it to the root of the tree where you extracted
 # the source (default to /usr/include/dcmtk/)
-
+#
+#
+# This file is able to find version of DCMTK that do or do not export
+# a DCMTKConfig.cmake file.
+#
+# IMPORTANT: A set of patches has been contributed to DCMTK
+# maintainers, as soon as:
+#   (1) it has been integrated upstream so that it is available in
+#   an official release (for example X.Y.Z),
+#   (2) code bases have been updated to build against X.Y.Z
+# This file could be removed.
+#
+# The set of patches is listed here: https://github.com/commontk/DCMTK/compare/79030ba...f461865
+#
+#
+# Waiting for this to happen, build systems will have to be able
+# to support different versions of DCMTK.
+#
+# On any given system, the following combination of DCMTK version could be
+# considered:
+#
+#         |   SYSTEM DCMTK      +      LOCAL DCMTK      |     Supported ?   |
+# ---------------------------------------------------------------------------
+# Case A  |   NA                +      [ ] DCMTKConfig  |         YES       |
+# ------------------------------------------------------|--------------------
+# Case B  |   NA                +      [X] DCMTKConfig  |         YES       |
+# ------------------------------------------------------|--------------------
+# Case C  |   [ ] DCMTKConfig   +      NA               |         YES       |
+# ------------------------------------------------------|--------------------
+# Case D  |   [X] DCMTKConfig   +      NA               |         YES       |
+# ------------------------------------------------------|--------------------
+# Case E  |   [ ] DCMTKConfig   +      [ ] DCMTKConfig  |         YES (*)   |
+# ------------------------------------------------------|--------------------
+# Case F  |   [X] DCMTKConfig   +      [ ] DCMTKConfig  |         NO        |
+# ------------------------------------------------------|--------------------
+# Case G  |   [ ] DCMTKConfig   +      [X] DCMTKConfig  |         YES       |
+# ------------------------------------------------------|--------------------
+# Case H  |   [X] DCMTKConfig   +      [X] DCMTKConfig  |         YES       |
+# ---------------------------------------------------------------------------
+#
+#  (*) See Troubleshooting section.
+#
+# Legend:
+#
+#   NA ...............: Means that no System or Local DCMTK is available
+#
+#   [ ] DCMTKConfig ..: Means that the version of DCMTK does NOT export a DCMTKConfig.cmake file.
+#
+#   [X] DCMTKConfig ..: Means that the version of DCMTK exports a DCMTKConfig.cmake file.
+#
+#
+#
+# In CTK commits 52d953 and 74b4b07, the FindDCMTK.cmake module has been updated to be able
+# to find both version of DCMTK ([ ] DCMTKConfig and [X] DCMTKConfig).
+#
+# It is a two steps process:
+#
+#   * Step 1:  Attempt to find DCMTK version providing a DCMTKConfig.cmake file. This is done
+#              with the help of ''
+#
+#   * Step 2:  If step 1 failed, rely on FindDCMTK.cmake to set DCMTK_* variables details below.
+#
+#
+#
+# Troubleshooting:
+#
+#    What to do if my project find a different version of DCMTK ?
+#
+#    Remove DCMTK entry from the CMake registry.
+#    Search for "CMake user package registry" on http://www.cmake.org/cmake/help/v2.8.9/cmake.html#command:find_package
+#
+#    Details: As some point, the DCMTK build tree was exported [1][2][3]. Indeed, before the set of
+#    patches discussed above has been contributed to upstream DCMTK, an initial implementation of
+#    a DCMTK build system exporting its build tree has been implemented and has been tested by some
+#    folks. This had the effect of populating the CMake registry.
+#
+#    Since Step1 does not exclude the CMake registry, when dealing with case E, the incorrect version of
+#    DCMTK could be found.
+#
+#    [1] http://slicer-devel.65872.n3.nabble.com/Packaging-seems-to-work-again-tp4028121p4028134.html
+#    [2] https://www.assembla.com/spaces/slicerrt/tickets/244-dcmtk_dir-vs--dcmtkconfig-cmake?comment=267984263#comment:267984263
+#    [3] http://www.cmake.org/cmake/help/v2.8.11/cmake.html#command:export
+#
+#
 #=============================================================================
 # Copyright 2004-2009 Kitware, Inc.
 # Copyright 2009-2010 Mathieu Malaterre <mathieu.malaterre@gmail.com>
@@ -37,7 +118,8 @@
 set(_SAVED_DCMTK_DIR ${DCMTK_DIR})
 
 #
-# First, try to use NO_MODULE
+# Step1: Attempt to find a version of DCMTK providing a DCMTKConfig.cmake file.
+#
 message(STATUS "Trying to find DCMTK expecting DCMTKConfig.cmake")
 find_package(DCMTK QUIET NO_MODULE)
 if(DCMTK_FOUND
@@ -54,6 +136,11 @@ message(STATUS "Trying to find DCMTK relying on FindDCMTK.cmake")
 # Restore the value reset by the previous call to 'find_package(DCMTK QUIET NO_MODULE)'
 set(DCMTK_DIR ${_SAVED_DCMTK_DIR} CACHE PATH "The directory containing a CMake configuration file for DCMTK." FORCE) 
 
+
+#
+# Step2: Attempt to find a version of DCMTK that does NOT provide a DCMTKConfig.cmake file.
+#
+
 # prefer DCMTK_DIR over default system paths like /usr/lib
 if(DCMTK_DIR)
   set(CMAKE_PREFIX_PATH ${DCMTK_DIR}/lib ${CMAKE_PREFIX_PATH}) # this is given to FIND_LIBRARY or FIND_PATH