[Development] Recommendations for 3rd-party QCH file installation folder for easy discovery?

[Friedrich W. H. Kossebau]

Thanks for all the replies so far. Seems this is not a topic where people 
working on Qt have (already) opinions or ideas about or at least some to share 
:)

Guess this needs to wait until there are more 3rd-party QCH files in the wild 
obviously, so the issues get more important and there is some base to discuss 
& plan any possible/needed improvements to Assistant, Creator and the qthelp 
system.
Will try now also the interest mailing list for any experiences/ideas.

For the record here my current conclusions:

Am Dienstag, 22. November 2016, 18:05:20 CET schrieb Friedrich W. H. Kossebau:
> two questions to anyone working on/with QCH files:
> 
> Q1: what would be a good system path pattern (on *nixoid systems) for
> Qt-based libraries to install their QCH files to?

While it was proposed to use some path below the package-owned resource 
folders (e.g. /usr/share/<package>/doc), this does not help with the use case 
easy discovery of QCH files and with the use case easy mass addition of dozens 
of them (like one day hopefully the case with the ones for all the KDE 
Framework libraries), e.g. by selecting them in one go in the file dialog (on 
the command line "assistant -register" even only takes one file it seems, so 
only experts with bash & find foo have an easy going ;) ).

Looking at other documentation format (systems) I see they have a specific 
folder, where installing some package specific documentation also 
automatically works as registration:
/usr/share/info/
/usr/share/man/

And seeing that KDE uses /usr/share/doc/HTML for documentation in html/
docbook(?) format I am for now proposing
	/usr/share/doc/QCH
as folder where packages would drop the QCH/qthelp system specific files, 
namespacing them by proper basenames "<libxyz>.qch" similar to what is needed 
with "<libxyz>.so".
This helps at least with the use-case of looking at the file system to find 
what QCH files are available, by being a central place to look at and also the 
use-case to pick multiple files in one go in Assistant's file dialog.

> Q2: And would/could there be some way to have 3rd-party QCH files
> automatically added to Qt Assistant, Creator & Co. on installation, to spare
> the user the additional manual step?

Given the concept of user specific collection files in Qt Assistant (no idea 
about Qt Creator here), automatically adding QCH help files on system install 
(assuming linux distribution here) to any collection files would not be nice 
anyway.

Still it might be nice to at least add them automatically to the default help 
file collection IMHO, this might serve the average of people who usually only 
work on one project where they only install the QCH files to the system the 
need anyway and also only use the default help file collection.

As it seems that Qt Assistant automatically adds (after restart) new QCH files 
it discovers in the QT_INSTALL_DOCS folder to the default help file 
collection, simply installing any 3rd-party QCH files into that folder would 
serve the use-case of automatic addition to Qt Assistant after install. And 
thus this is what I propose now as well to do. After all installing into the 
Qt system dirs is also done already for 3rd-party plugins, mkspec files or QML 
imports.

See the above conclusions (and any follow-up ones) being implemented in the 
new CMake macros proposed to become part of the Extra-CMake-Modules here: 
	https://phabricator.kde.org/D2854
(custom version even already committed to development versions of KDE's 
KProperty & KReport libs, with more to come).

Cheers
Friedrich