Not sure what you mean, please point out the issue you see here with more details :)

The plan here is:
if KDE_INSTALL_USE_QT_SYS_PATHS is set, install QCH files to QT_INSTALL_DOCS, if not, some "normal" dir (there is no standard dir for QCH in general currently, everybody installs their 3rd-party QCH files somewhere).
See thread http://lists.qt-project.org/pipermail/development/2016-November/027856.html and especially the latest http://lists.qt-project.org/pipermail/development/2016-November/028001.html
Feedback is very welcome.

I mean, addition of qch subdir is 'your' invention here.
If Frameworks were to use only qmake build-system, i'm sure qch files would end up in QT_INSTALL_DOCS directory.
I.e. for KDE_INSTALL_USE_QT_SYS_PATHS=ON the paths are Qt's, so are with KDE_INSTALL_USE_QT_SYS_PATHS=OFF, just that for the latter case they are read from sources, opposed to querying qmake.

But that is the same for the current QTPLUGINDIR, QTQUICKIMPORTSDIR, & QMLDIR, no? They also only get set to the Qt system paths if KDE_INSTALL_USE_QT_SYS_PATHS=ON, otherwise get set to something based on general LIBDIR.
(I would have liked to put the setting of QTQCHDIR next to these other ones, but at that time DATAROOTDIR is not yet defined, so had to create a separate if-else)
And especially if installing multiple versions of the same dir (e.g. for different projects or as developer of the lib), it will be needed to optionally not install into the Qt system path, but point all the tools via ENV variables or other ways to the matching plugins or documentation.

Right. But if you install a framework to same prefix as Qt, you get free recognition of plugins, qml imports, etc... This is valid for both /usr and custom prefix installs.
I guess what i want to say is that there is IMHO no reason this should also not work for QCH docs.

But isn't this free recognition happening via KDE_INSTALL_USE_QT_SYS_PATHS as well?
At least this is how I understand https://cgit.kde.org/extra-cmake-modules.git/tree/kde-modules/KDEInstallDirs.cmake#n442 to work.
This is also what I rely on, as I agree that it should also happen when installing to the same prefix :)

It is :) But with this latest revision it is not when that var is off =) I'm saying that for both cases it should happen.

Fear I am still missing what you mean. So let's go explicitely, here is what I understand to happen:

There are six different cases when using this macro and on the first invocation of cmake, from the combinations of installing to a different prefix or the same prefix as Qt (2 variants) versus KDE_INSTALL_USE_QT_SYS_PATHS being not set/defined, set to ON, set to OFF (3 variants).

In these 3 cases plugins, QCH & Co. will be all installed to Qt system dirs and thus automatically picked up by Qt, without the need for further env var settings:

• -DKDE_INSTALL_USE_QT_SYS_PATHS=ON, different prefix
• -DKDE_INSTALL_USE_QT_SYS_PATHS=ON, same prefix
• KDE_INSTALL_USE_QT_SYS_PATHS not passed as argument, same prefix (so

In the three other cases plugins, QCH & Co will be installed in dirs and need further env var settings, for Qt (and Qt Assistant) to also pick up the stuff.

Where do we see things differently? And just to make sure, you have seen the right lines at the link I passed before, how _default_KDE_INSTALL_USE_QT_SYS_PATHS is set to ON if the same prefix is used?

Hm, i guess i haven't checked KDEInstallDirs in a while. Somehow i remember KDE_INSTALL_USE_QT_SYS_PATHS was only activated by default if CMAKE_INSTALL_PREFIX was /usr.

Ok, so the non-recognition part should not happen that often -> I'm assuming qch files are looked up as QLibraryInfo::DocumentationPath (so, QT_INSTALL_DOCS) + *qch.

So with your path, they will not be found (yeah with different prefix they aren0t still found, but with qch/ subdir user needs one additional envar for KF5 qch's - imagine you need to export QT_PLUGIN_PATH for Qt plugins, and one more path for KF5 plugins).
I don't see a reason to append qch subdir to installation location -> as if you're intentionally hiding those files ;-)