[Development] Assistant WebKit/WebEngine support

[Eike Ziller]

> On 25. Jun 2019, at 23:53, Konrad Rosenbaum <konrad at silmor.de> wrote:
> 
> Hi,
> 
> On 6/25/19 9:59 PM, Tor Arne Vestbø wrote:
>> On 25 Jun 2019, at 21:30, Konrad Rosenbaum <konrad at silmor.de> wrote:
>>> Pardon my lingo,
>> You should be able to communicate your points without that kind of lingo. Try better.
>> 
>>> It is documentation for developers for crying out loud! Its purpose is not to win any design prices, but to educate the developers.
>> Please stop putting up straw-men, it’s not helping this discussion at all.
> 
> Okay, let's formulate this in a way that hopefully doesn't offend you
> and doesn't seem like a straw-man to you.
> 
> 
> Qt6 has a couple of options for documentation, none of them are ideal:
> 
> 
> Option 1: leave everything as is with a QTextBrowser based assistant and
> some tweaks in the qch files.
> Pros: no additional work required; all current features and use cases
> stay supported; good enough for a lot of developers
> Con: looks ugly enough to actually offend visually sensitive developers.
> 
> 
> Option 2: put some elbow grease into QTextBrowser and make it understand
> some more tags and more CSS.
> Pros: documentation becomes visually more pleasing; minimal dependencies
> by assistant - easy to build and easy to bundle with applications;
> embedding in Creator or KDevelop etc. stays easy to do
> Positive side effect: users will love it, since it becomes much easier
> and flexible to use QTextBrowser in their own applications
> Con: someone actually has to put in the work

And we really miss a good, small HTML+CSS viewer for Qt. Currently we offer either crap (QTextBrowser, sorry for the harsh words), or something huge, that does too much, and is more difficult to deploy (QtWebEngine).
QtWebKit was an bearable compromise at the time, it didn’t hurt so much as QtWebEngine.

Option 2 1/2: Leave QTextBrowser alone but create a lightweight HTML+CSS viewer, possibly based on something like https://github.com/litehtml/ .
Pros: documentation becomes visually more pleasing; dependencies really only contain what is needed for HTML+CSS; a solution benefits other developers using Qt
Con: someone actually has to put in the work

> Option 3: bring back WebKit
> Pros: looks beautiful; uses up less memory than WebEngine
> Cons: someone has to put up lots of work to actually support WebKit;
> uses up lots more memory than QTextBrowser; adds a dependency to
> assistant (makes it less useful for redistribution); embedding in IDEs
> is slightly more complex and adds a dependency

I agree with Thiago that this also requires WebKit to be updated with security fixes. It will potentially show downloaded content from anywhere, and it’s not nice if someone can offer a malicious qch, using known security issues in WebKit. And with JavaScript etcetera the “attack area” is much larger than actually necessary for browsing documentation.

> Option 4: convert to WebEngine
> Pros: looks great; currently supported browser engine, only little
> porting work
> Cons: horrible memory footprint; acute terminal featuritis; adds lots of
> dependencies (disqualifies it for most/many people redistributing it);
> does not work on all platforms supported by Qt (makes assistant less
> useful or even useless to those users); embedding in IDEs becomes much
> more difficult (dependencies and #ifdef's for unsupported platforms)

What is the state of Linux distributions and QtWebEngine?
I remember that there were some concerns, but neither remember details, nor how it went on.
Technically the QTextBrowser backend would still be available as a fallback, but that doesn’t help if the documentation starts to use features/CSS that is not supported by it.

> Option 5: use WebView
> Pros: might look good
> Cons: either looks bad or adds whatever component WebView wants to use
> as a dependency; unpredictable results

We also either need to be able to register a scheme handler for qthelp, or use a local server for the help.
Also, WebView can use the “platform” API, but on Linux there is none. So we need an implementation on Linux based on one of the other options in any case.

> Option 6: use plain platform browser to show local files
> Pros: minimal footprint; assistant can be retired; guaranteed good rendering
> Cons: you never know which browser the user installs; abandon QCH
> format; implementing search becomes a horrible mess of JS and other
> files - requires extensive tool support to generate this - doubtful that
> it will always work; forget embedded viewers - this would require
> WebEngine or WebKit again; some users will hate the fact that assistant
> is missing or at least unsupported
> 
> 
> Option 7: platform browser plus server process to deliver help via local
> HTTP
> Pros: like Option 6, but search becomes easier to implement
> Cons: like Option 6, except search; someone needs to implement a simple
> HTTP server (not that hard, but requires some work) and a search engine
> (slightly harder, but solvable)

Also I see usability issues (for 6+7), since we probably cannot control where the documentation opens when we request the browser to do so.
Opening a new tab/window any time the user presses F1 in Qt Creator would be pretty bad.
Note that we need index information for context help in Qt Creator, so we’ll not completely get rid of (something like) qch in any case.

> My personal favorite would be Option 2 (better QTextBrowser), followed
> by Options 1 (status quo) and 3 (WebKit) in no particular order. But
> since I'm not willing to put in any serious work or pay for it - my vote
> does not count - I'm just a user. ;)
> 
> Feel free to correct/critique my assessment and to add more options if
> you see any. Otherwise: chose your poison.
> 
> 
> 
>     Konrad
> 
> 
> <pEpkey.asc>_______________________________________________
> 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