D8211: KDevelop/Documentation : implementation of a QTextBrowser-based viewer

Fri Oct 20 05:58:36 UTC 2017

kossebau added a comment.

  In https://phabricator.kde.org/D8211#157208, @rjvbb wrote:

  > >   Then with newer doxygen version the default CSS results in unreadable titles e.g. on method sections. Which makes the docs rather unusable.
  >
  > Then please post screenshots because I don't see any of that.

  Sorry, my bad here in uploading an old QCH file which missed half of the meat, i.e. did not have subclass information (thus missing all the "* inherited from" sections which are the biggest pain).
  Please download and try again, newer version has been uploaded to same place.

  And preview here what I mean (left Qt Assistant with QTB, right KDevelop with QWE):

  Sections cannot be toggled, are open/closed randomly after loading (no pattern seen over the time):
   F5439139: Spectacle.hc7421.png <https://phabricator.kde.org/F5439139>

  Method titles are partially hidden, tags like virtual,visibility,abstract hard to read due to missing spacing ()
  F5439130: Spectacle.PE7421.png <https://phabricator.kde.org/F5439130>

  I had tried to use Qt Assistant (so QTB) with that a few weeks, but it was a pain. It is better than nothing as one can draw some info out of the docs, but it is not a joyful experience, so I often escaped to the online docs when I had network. Until I fixed the embedded documentation viewer to wok as I need it (still need to clean-up and push the rest of it, only merged the bit for the search so far).

  So as documentation power-user my strong feedback is: QTB sucks at least for doxygen-created documentation material.

  > The contextual help popups already use QTB, do you see any issues with those?

  That is not really related, due to not being affected by JavaScript and CSS, unless the extraction done by IDocumentation::description() implementations pulls out too much non-content stuff.

  >>   The screenshot of the ECM docs linked above shows that content is rendered, indeed. But really, does it qualify as "fine"? Please take another look and even more try to make use of the document during development.
  > 
  > It's more than good enough for me - if I use the embedded doc toolview. By now it should be clear that I don't, most of the time, but instead send the links to open to a remote-controlled Assistant copy.

  Reads to me like "it is good enough for me because I do not use it (and thus do not care but you are invited to collaborate)". This approach is not really "collaborative", or?

  So again, why this work? To me it seems you want to build KDevelop without QWebEngine or QWebKit, and also only use external documentation viewers, no embedded ones. Which is fine in itself, I see no issue with supporting that as option.
  But then the approach in this patch is only an indirect solution to achieve your goal, while making life of those more complicated who want to maintain and develop the embedded documentation viewer further.
  And as someone who has some WIP to improve the current embedded documentation viewer (e.g. with bookmarks or multiple views), I really am not happy about having in the future also to care for another code variant, which itself might not really be used by many.

  Let's read now again the reasoning for this patch :
  "I've long thought it overkill to embed an almost full-fledged webbrowser inside KDevelop just for browsing Qt help (and even more so for the simpler CMake docs and man pages)."
  This seems flawed to me. Software is developed to serve a purpose. one collects requirements, then gets out to find a solution, ideally be reusing existing products.
  But here the rationale is some "thinking", without numbers to prove some "overkill". And by listing simply a few examples which are claimed to fit that "thinking". No detailed analysis given. 
  Purpose of this patch seems: get rid of some dependency.

  "Qt's Assistant uses QtTextBrowser by default; "
  Build system says something else: http://code.qt.io/cgit/qt/qttools.git/tree/src/assistant/assistant/assistant.pro uses QtWebKit is present, only if not falls back to QTextBrowser

  "As far as I can tell it works more than well enough to peruse the documentation the way I would in an embedded viewer. The layout is somewhat simpler, more in line with use in an embedded viewer; I find it distracts less from the source."
  If the layout is simpler, this is not by design but only by accidentally unsupported CSS features. Which means the layout  is not completely designed and thus might be broken, lhard to read and look shitty. Also why should the same documentation content look more complex in a stand-alone viewer app? This does not make sense to me, I expect content to be simple to parse in both cases.

  "I would suggest to make [using QTextBrowser] the default mode since it doesn't require extra dependencies, and focus on adding proper support for opening links in an external browser of choice at least for the QtHelp documentation." 
  The default mode means, the recommended mode for everyone. QWebEngine and/or QWebKit are available on most platforms and usually already installed (linux-centric thinking, but then closed source platforms are second class). QTextBrowser as default mode also means reduced and for some documentation broken functionality, so not a proper default. Runtime costs have yet to be measured, so the price is unknown. So "[being] extra dependencies" is only interesting for niche operating systems or custom development setups and should not dominate.
  And making something default where parts of the work ("proper support for opening links in an external browser") are yet to be solved is premature.

  KDevelop is by definition a "feature-full, plugin extensible IDE for C/C++ and many other programming languages.". So there could be lots of documentation material besides the "simpler CMake docs and man pages" and which might need more than QTB can support. Even QCH files, given there is no real specification, can in theory contain full HTML5-powered webpages with interactive WebGL examples. (There is a reason why Qt Assistant/Qt Creator had QtWebKit as default implementation for documentation viewer when available, until that came deprecated as module itself).

  IMHO either there is a proper embedded documentation viewer or documentation viewing is delegated completely to external applications, But having a crippled embedded documentation viewer by design does not serve a real purpose. KDevPlatform is built on the idea of plugins with interfaces. And when we want to have a plugin option for the delegation of documentation viewing to external applications, that should be done by designing a new interface to abstract the invocation of documentation display, where the current documentation tool view could be then coming from one plugin serving that interface (which then has the QWK or QWE dependencies), and delegation to external applications be done by another one. Right now instead this patch feels like pushing for crippling the existing embedded documentation viewer in favour of using external applications. That's not "collaborative" to me.

REPOSITORY
  R32 KDevelop

REVISION DETAIL
  https://phabricator.kde.org/D8211

To: rjvbb, #kdevelop
Cc: croick, kossebau, aaronpuchert, flherne, arichardson, apol, kdevelop-devel, geetamc, Pilzschaf, akshaydeo, surgenight, arrowdodger
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/kdevelop-devel/attachments/20171020/b1a90545/attachment.html>