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

[Kevin Kofler]

Friedrich W. H. Kossebau wrote:
> 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.

As a distro packager, I think this is definitely the way to go. Tracking 
what package any individual file comes from is what the package manager is 
for. This is also how it works for manpages, .desktop files, etc.

> 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,

Why would we need to invent yet another directory? QT_INSTALL_DOCS in Fedora 
is currently /usr/share/doc/qt5, I think that is perfectly fine. It is also 
versioned, so you do not get, e.g., kdelibs4 apidocs in the Qt 5 Assistant, 
or the other way round.

I think you should just use the existing QT_INSTALL_DOCS directory and stick 
to it, no need to reinvent the wheel and break compatibility.

Kevin Kofler

___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

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

[Tomasz Siekierda]

On 30 November 2016 at 17:14, Friedrich W. H. Kossebau  wrote:
>
> And seeing that KDE uses /usr/share/doc/HTML for documentation in html/
> docbook(?) format I am for now proposing
> /usr/share/doc/QCH

Sounds good.

And just to add my voice - I think automatic pickup of QCH files is
something very worth introducing (and not only on Linux).
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [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//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 ".qch" similar to what is needed 
with ".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

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

[Kevin Kofler]

Friedrich W. H. Kossebau wrote:
> Though your comment points to the issue of multiple versions of some libs
> being installed at the same time: if their respective QCH files are all
> being automatically added in Qt Assistant & Co., this will result in some
> confusion, especially when it comes to resolving version-less qthelp://
> urls. That needs more thinking.

Distros will typically only allow one version of the QCH to be installed at 
the same time to begin with.

Kevin Kofler

___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

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

[Friedrich W. H. Kossebau]

Hi,

Am Donnerstag, 24. November 2016, 11:08:56 CET schrieb Lisandro Damián Nicanor 
Pérez Meyer:
> On jueves, 24 de noviembre de 2016 07:38:20 ART Uwe Rathmann wrote:
> > On Tue, 22 Nov 2016 18:05:20 +0100, Friedrich W. H. Kossebau wrote:
> > > Q1: what would be a good system path pattern (on *nixoid systems) for
> > > Qt-based libraries to install their QCH files to?
> > 
> > Qwt ( http://qwt.sf.net ) offers a qch file and is available for quite
> > some time. So you could check, what is common practice among distro
> > packagers.
> > 
> > F.e. on my box ( OpenSusSE 12.2 ) it is simply not part of qwt6-devel-
> > doc. But the OpenSuSE package maintainer seems in general not being aware
> > of these Qt specific files as the installation of the feature files is
> > also broken.
> > 
> > But the rest of the docs can be found below /usr/share/doc/packages/qwt6-
> > devel-doc and IMO this is where I would expect to find qwt.qch as well.
> > 
> > Maybe other distros can give you a better hint.
> 
> At least on Debian I would push them to /usr/share//doc/

I see, thanks for the info.
Even more, "find /usr/share/ -name doc" tells me on my openSUSE Tumbleweed 
that indeed
/usr/share//doc/
is more popular than
/usr/share/doc/packages/

And I see that GammaRay puts their QCH file here directly to
/usr/share/gammaray/gammaray-api.qch

Meh. There are better places for variety and personality :)

Hm. Currently I am tempted to solve this issue for now by defaulting the 
install of the 3rd-party QCH files directly to the Qt system folder with the 
Qt QCH files (the one of the Qt linked against).
Seems at least Qt Assistant automatically adds any new QCH file placed there, 
so this would solve the discoverability issue. After all if someone installed 
a package with the QCH file, they do want to use it usually...

Cheers
Friedrich
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

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

[Friedrich W. H. Kossebau]

Hi Uwe,

Am Donnerstag, 24. November 2016, 07:38:20 CET schrieb Uwe Rathmann:
> On Tue, 22 Nov 2016 18:05:20 +0100, Friedrich W. H. Kossebau wrote:
> > Q1: what would be a good system path pattern (on *nixoid systems) for
> > Qt-based libraries to install their QCH files to?
> 
> Qwt ( http://qwt.sf.net ) offers a qch file and is available for quite
> some time. So you could check, what is common practice among distro
> packagers.
> 
> F.e. on my box ( OpenSusSE 12.2 ) it is simply not part of qwt6-devel-
> doc. But the OpenSuSE package maintainer seems in general not being aware
> of these Qt specific files as the installation of the feature files is
> also broken.

>From a quick look I would guess the reason for no qwt.qch being part of any 
package with openSUSE is that it is only available as a separate download, so 
not part of the sourcecode tarball. Best file a bug about this, most packagers 
do not eat all their dog food, at least not until the last bit(e), and if no-
one has told them they will not know. Been there, done that :)

That is also why I started this thread, to make sure that those QCH files for 
all the KDE Framework libs and the other libs from KDE also can make it all 
the way to the end-user, and are not lost on the track or end up unseen in the 
corner.

So let's join forces here as creators of 3rd-party QCH files and form an 
interest group :)

BTW, seeing you have used doxygen 1.8.11 for creating the latest 
qwt-6.1.3.qch, you might be interested in this patch to doxygen perhaps:
https://github.com/doxygen/doxygen/pull/541
"Fix: Add missing jquery.js, dynsections.js & optional svgpan.js to QCH file"

And this bug report about the hardcoded JavaScript in QCH files from doxygen:
https://bugzilla.gnome.org/show_bug.cgi?id=773715

Seems things have regressed a little since https://blog.qt.io/blog/2009/01/15/
creating-qch-files-from-doxygen-revisited/ :(

> But the rest of the docs can be found below /usr/share/doc/packages/qwt6-
> devel-doc and IMO this is where I would expect to find qwt.qch as well.
> 
> Maybe other distros can give you a better hint.

Okay, thanks for this info.

> > 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?
> 
> To me one of the most error prone things is loading 3rd party plugins to
> the creator. This has mostly to do with binary incompatibilities between
> the libraries used for development and the one used by the Creator
> ( Assistant is less bad as being built together with Qt libs ) , but the
> fact, that plugins are loaded "automatically" from some directories is
> part of the problem.
> 
> Coming from having experienced maximal user frustration with this
> approach I wouldn't recommend to establish such an automatism.

? I was talking about the QCH files only, so no code/binaries involved :)

Though your comment points to the issue of multiple versions of some libs 
being installed at the same time: if their respective QCH files are all being 
automatically added in Qt Assistant & Co., this will result in some confusion, 
especially when it comes to resolving version-less qthelp:// urls. That needs 
more thinking.

One wild idea I had was to have IDEs know which QCH files belong to which 
libraries, and using the info they can get from the buildsystem about the used 
libs in the current project automatically activate the respective QCH files in 
the API documentation viewer module, or at least have them available as 
proposals. Might be handy when starting or joining a project :) Some long-term 
idea for now.

Cheers
Friedrich
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

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

[Lisandro Damián Nicanor Pérez Meyer]

On jueves, 24 de noviembre de 2016 07:38:20 ART Uwe Rathmann wrote:
> On Tue, 22 Nov 2016 18:05:20 +0100, Friedrich W. H. Kossebau wrote:
> > Q1: what would be a good system path pattern (on *nixoid systems) for
> > Qt-based libraries to install their QCH files to?
> 
> Qwt ( http://qwt.sf.net ) offers a qch file and is available for quite
> some time. So you could check, what is common practice among distro
> packagers.
> 
> F.e. on my box ( OpenSusSE 12.2 ) it is simply not part of qwt6-devel-
> doc. But the OpenSuSE package maintainer seems in general not being aware
> of these Qt specific files as the installation of the feature files is
> also broken.
> 
> But the rest of the docs can be found below /usr/share/doc/packages/qwt6-
> devel-doc and IMO this is where I would expect to find qwt.qch as well.
>
> Maybe other distros can give you a better hint.

At least on Debian I would push them to /usr/share//doc/
 
> > 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?
> 
> To me one of the most error prone things is loading 3rd party plugins to
> the creator. This has mostly to do with binary incompatibilities between
> the libraries used for development and the one used by the Creator
> ( Assistant is less bad as being built together with Qt libs ) , but the
> fact, that plugins are loaded "automatically" from some directories is
> part of the problem.
> 
> Coming from having experienced maximal user frustration with this
> approach I wouldn't recommend to establish such an automatism.

Note he says qch. I don't think it uses plugins for that.


-- 
Must it be assumed that because we are engineers beauty is not
our concern, and that while we make our constructions robust
and durable we do not also strive to make them elegant?
Is it not true that the genuine conditions of strength always
comply with the secret conditions of harmony?
 Gustave Eiffel, 1887

Lisandro Damián Nicanor Pérez Meyer
http://perezmeyer.com.ar/
http://perezmeyer.blogspot.com/


signature.asc
Description: This is a digitally signed message part.
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

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

[Uwe Rathmann]

On Tue, 22 Nov 2016 18:05:20 +0100, Friedrich W. H. Kossebau wrote:

> Q1: what would be a good system path pattern (on *nixoid systems) for
> Qt-based libraries to install their QCH files to?

Qwt ( http://qwt.sf.net ) offers a qch file and is available for quite 
some time. So you could check, what is common practice among distro 
packagers.

F.e. on my box ( OpenSusSE 12.2 ) it is simply not part of qwt6-devel-
doc. But the OpenSuSE package maintainer seems in general not being aware 
of these Qt specific files as the installation of the feature files is 
also broken.

But the rest of the docs can be found below /usr/share/doc/packages/qwt6-
devel-doc and IMO this is where I would expect to find qwt.qch as well.

Maybe other distros can give you a better hint.

> 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?

To me one of the most error prone things is loading 3rd party plugins to 
the creator. This has mostly to do with binary incompatibilities between 
the libraries used for development and the one used by the Creator 
( Assistant is less bad as being built together with Qt libs ) , but the 
fact, that plugins are loaded "automatically" from some directories is 
part of the problem.

Coming from having experienced maximal user frustration with this 
approach I wouldn't recommend to establish such an automatism.

Uwe


___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

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

[Friedrich W. H. Kossebau]

Hi,

(resending here instead of qt-creator@, as hinted to by Eike)

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?

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?


For Q1, I see all the Qt ones are on my system at
/usr/share/doc/packages/qt5/*.qch

So far I would have guessed
/usr/share/doc/$lib/$lib.qch
might be a good location. So what patterns do people use for their QCH files 
when delivering to others as part of an install?


For Q2, having to manually add all QCH files one-by-one to Qt Assistant & Co. 
does not nicely scale if there are a dozen and more 3rd-party QCH files (think 
e.g. all the non-KF5 and KF5 libs created in the KDE community).

Would it perhaps make sense to have some registration system, so QCH files can 
register themselves somewhere, so Qt Assistant/Creator & other documentation 
viewers know what is present on the system?
Would some simple sym-linking into some generic dir make sense for a start? 
The /usr/share/doc/packages/qt5 perhaps should be reserved to original Qt 
ones, but perhaps some separate generic dir like
/usr/share/doc/qch
would work? Or something based on ENV vars, which would avoid hardcoding such 
dirs into Qt Assistant & Co.?

Actually it would be nice if an installed QCH file would be automatically 
added to Qt Assistant & Co., after all one installed it for a purpose. Are 
there any plans with regard to that?


Background:
I am currently working on adding QCH support to the buildsystem for all the 
libraries of the KDE Frameworks (and other (KDE) library products), for the 
generation of QCH files during builds (https://phabricator.kde.org/D2854).

This is done with the goals that the API documentation of KDE Frameworks 
libraries can be viewed/used offline with e.g. Qt Assistant, Qt Creator or 
KDevelop, and that packagers/distributors of those libraries automatically 
from the build also have a QCH file matching the very API version of the 
library for packaging (& inclusion into in any package update mechanism).

The implementation of this support is done by new CMake macros which for now 
make use of the QCH generation feature of doxygen. The macros even support the 
automatic qthelp:// linking to documentation of base libraries, like the Qt 
ones.

So once that support works, there will be dozens of QCH files which currently 
would each need manual work by the user to have them added to Qt Assistant & 
Co. Not perfect!

Cheers
Friedrich

___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development