On 6/26/19 10:09 AM, Eike Ziller wrote: >> On 25. Jun 2019, at 23:53, Konrad Rosenbaum <kon...@silmor.de> wrote: >> >> Hi, >> >> On 6/25/19 9:59 PM, Tor Arne Vestbø wrote: >>> On 25 Jun 2019, at 21:30, Konrad Rosenbaum <kon...@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@qt-project.org >> https://lists.qt-project.org/listinfo/development > _______________________________________________ Development mailing list Development@qt-project.org https://lists.qt-project.org/listinfo/development