[Development] Assistant WebKit/WebEngine support

[Nikolai Kosjar]

On 6/26/19 10:09 AM, Eike Ziller wrote:
>> 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.

That's fine for my *personal* use cases with Qt Creator and using help 
in there. While it would be desirable to have the same look and feel as 
on https://doc.qt.io/, I never had a problem with that. If I'm using 
help mode, I'm looking for a particular information and the styling 
never got in my way. So that's 95% fine with me.

But we are having this discussion/thread here, so we can rule this out, 
except for a fallback of course.

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

+1 for this one, option 2, or a *heavily* reduced/stripped webengine, 
depending on the amount of estimated work.

Estimating this is also 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
>