[Development] Assistant WebKit/WebEngine support

Fri Jun 28 10:24:00 CEST 2019

> On 27. Jun 2019, at 15:46, Palaraja, Kavindra <KPalaraja at luxoft.com> wrote:
> 
> On 27.06.19, 10:47, "Development on behalf of Jaroslaw Kobus" <development-bounces at qt-project.org on behalf of Jaroslaw.Kobus at qt.io> wrote:
> 
> QTextBrowser promises to render rich text - isn’t it what we want for showing help? If QTextBrowser isn’t able to render properly the static help files - what is the other typical usage of it? Why we claim that QTextBrowser is able to do things, which in fact it can't? This doesn't show a fair message to the user, if we - for our purposes - don't use tools which we should.
> ....
> 
> OK, if we can't use QTextBrowser, then what are our other options?
> 
> 
> IMO, we should make a clear requirements on what we want and what we don’t want for help viewer. There is no need for networking, means we even shouldn’t try to compile it against network module. Turning the networking functionality at runtime is not enough. We should make a clear separation, on what the viewer should support (like html, css), what it may potentially support in the future (we ensure we don’t close the door, e.g. playing offline videos), and what it shouldn’t support, never (networking, javascript (???), much more...). We should define it first and than choose the right solution. Not like: let’s choose webengine, it may do everything. Currently it looks like the webengine supports everything and it’s way too much.
> 
> 
> Here are the requirements, based on what other developer tools and platforms have:
> 
> 1. The ability to copy code snippets directly from Qt's documentation (Creator or Web) and paste it into your code: https://docs.microsoft.com/en-us/cpp/linux/configure-a-linux-project?view=vs-2019

That indeed probably uses JavaScript + fancy function call on the document object. (Side note: That doesn’t mean that one couldn’t implement that behavior with a no-JavaScript offline browser as well.)

> 2. The ability to track what has changed in Qt's APIs from version to version with a dropdown box, where you can select the SDK version and then the documentation rendering dynamically adapts to show what's new, what was changed, and what was deprecated. This goes all the way down to every single type. Notice how the context changes when you select a different XCode SDK, in this case: https://developer.apple.com/documentation?changes=latest_major

I don’t think such a combo box can be implemented offline the same as online, since offline it is not predefined which versions are actually there (and where).

> 3. The ability to teach a customer, incrementally, step-by-step, how to use a new Feature. Think of teaching a Designer how to use QML or Qt 3D Studio in a simple way: https://developer.apple.com/tutorials/swiftui/creating-and-combining-views Scroll down this page, slowly, and see how its dynamic content changes to teach high-level concepts in a beautiful way. Reference documentation is not the only type of documentation people read in an IDE. Quite the contrary. This feature would also be amazing for customers who need to port from QMake to CMake.

Actually I don’t like that I see the details of whatever step happens to be at the top, instead of whatever step I’m actually interested in (which I wouldn’t normally scroll to the top). Anyhow that might be personal preference.
In any case IMO these kinds of tutorials do not have to show integrated into the IDE. They work perfectly in an external browser (offline or online). (*)
What I think must be integrated into the IDE though is API documentation, so things like context help and looking up API from the index works nicely.

Interestingly I don’t find these features of Apple’s documentation (2+3) in the documentation integrated into Xcode. There I only find a clean minimal API documentation browser. When I e.g. click on links to examples an external browser opens.

(*)
Eclipse has (or had?) integrated tutorials with links / buttons that actually perform actions in the IDE for you while you follow the tutorial. This would be difficult online or in an external browser without the ability to register special URL/scheme handlers.
If someone has interest I did some limited experiments in Qt Creator with that here: https://codereview.qt-project.org/c/qt-creator/qt-creator/+/102110

> 4. The ability to categorize different types of tips, Notes vs. Important hints: https://docs.microsoft.com/en-us/xamarin/android/platform/files/
> 5. The ability to mark certain code snippets as not recommended, for example, comparing between best practices vs. less-performant code to give more hints to developers: Rust does this well: https://doc.rust-lang.org/book/ch16-01-threads.html#using-move-closures-with-threads

4+5 are covered by HTML+CSS without any dynamic or interactive capabilities.

Again, I’m not in principle against the above functionality,
but I don’t want us to pay the price that is imposed by a full-blown QtWebEngine. If we cannot severely strip that down, that price is much higher than necessary for HTML+CSS, and even for HTML+CSS+JavaScript.

Br, Eike

> This is the competition Qt is up against today and Qt cannot choose to apply concepts like that because of Qt Assistant and Qt Creator.
> 
> 
> PS. Kavindra, yes, the goal of this thread is to address your issues. But please, let’s consider all the technical possibilities, before the decision on which way to choose is made. And please don’t stop considering changes in QTextBrowers, just because noone fixed it so far (for many years). It would be really handy if we have a bugreport with exact description of which html tags / attributes / css are broken in QTextBrowser. It would give an overview of how much needs to be done there. The evidence like: we tried before and failed, doesn't tell too much.
> 
> OK, so how would we patch QTextBrowser? How many more tickets should be filed?
> 
> * https://bugreports.qt.io/browse/QTBUG-67439 -- says that style sheets are not being parsed correctly in Assistant. The customer looked for info on how the QTextBrowser used in Assistant parse's stylesheets but hasn't been able to find any information and they were hoping to modify their CSS to parse this correctly. So we don't even give our customers this information.
> * https://bugreports.qt.io/browse/QTBUG-33336 -- there's a comment here in the ticket that says 'Please bear in mind that QTextBrowser is not a HTML viewer and will never handle all possible dialects of HTML sufficiently.... Displaying 3rd party web content which is not under your control is something which requires a fullblown web engine.... This will never be supported in QTextBrowser, as it would mean something like duplicating WebKit (WebEngine) inside of QtGUI, which would of course defeat its purpose."
> 
> 
> Kavindra.
> 
> 
> 
> 
> ________________________________
> 
> This e-mail and any attachment(s) are intended only for the recipient(s) named above and others who have been specifically authorized to receive them. They may contain confidential information. If you are not the intended recipient, please do not read this email or its attachment(s). Furthermore, you are hereby notified that any dissemination, distribution or copying of this e-mail and any attachment(s) is strictly prohibited. If you have received this e-mail in error, please immediately notify the sender by replying to this e-mail and then delete this e-mail and any attachment(s) or copies thereof from your system. Thank you.
> _______________________________________________
> Development mailing list
> Development at qt-project.org
> https://lists.qt-project.org/listinfo/development

-- 
Eike Ziller
Principal Software Engineer

The Qt Company GmbH
Rudower Chaussee 13
D-12489 Berlin
eike.ziller at qt.io
http://qt.io
Geschäftsführer: Mika Pälsi,
Juha Varelius, Mika Harjuaho
Sitz der Gesellschaft: Berlin, Registergericht: Amtsgericht Charlottenburg, HRB 144331 B