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
_______________________________________________
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development
