> On Jun 28, 2019, at 10:24, Eike Ziller <eike.zil...@qt.io> wrote: > > > >> On 27. Jun 2019, at 15:46, Palaraja, Kavindra <kpalar...@luxoft.com> wrote: >> >> On 27.06.19, 10:47, "Development on behalf of Jaroslaw Kobus" >> <development-boun...@qt-project.org on behalf of jaroslaw.ko...@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.
And regarding price there’s still the question of supported platforms for Assistant. > 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@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.zil...@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 > > _______________________________________________ > Development mailing list > Development@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.zil...@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 _______________________________________________ Development mailing list Development@qt-project.org https://lists.qt-project.org/listinfo/development
