KTextEditorPreviewPlugin 0.2.0

KTextEditorPreviewPlugin 0.2.0 has been released.

The KTextEditorPreviewPlugin software provides the KTextEditor Document Preview Plugin, a plugin for the editor Kate, the IDE KDevelop, or other software using the KTextEditor framework.

The plugin enables a live preview of the currently edited text document in the final format, in the sidebar (Kate) or as tool view (KDevelop). So when editing e.g. a Markdown text or an SVG image, the result is instantly visible next to the source text. For the display the plugin uses that KParts plugin which is currently selected as the preferred one for the MIME type of the document. If there is no KParts plugin for that type, no preview is possible.

Download from:
https://download.kde.org/stable/ktexteditorpreviewplugin/0.2.0/src

sha256:
ab54382dfd8e88247b53b72fdd9b259feb7c0266300b604db899edf0828677ae ktexteditorpreviewplugin-0.2.0.tar.xz

Signed with my new PGP key
E191 FD5B E6F4 6870 F09E 82B2 024E 7FB4 3D01 5474
Friedrich W. H. Kossebau
ktexteditorpreviewplugin-0.2.0.tar.xz.sig

Change since 0.1.0

  • Add dropdown menu to toolbar with the main menu of the KParts plugin
  • Add About dialog for the currently used KParts plugin (invokable from the new dropdown menu)

Notes

Long term the plan is to merge this plugin into the Kate repository, or some new separate KTextEditor-Plugins repo, ideally already for KDE Applications 17.12.

For now though this plugin is in its own repository to allow an initial independent quick release cycle phase, following the release-often-and-early mantra. With the help of your feedback (file your issue) that should make the features of the plugin the ones you like to have rather soon.

Developers: Improve your favourite KParts plugin

While a usual KParts plugin works out of the box, for a perfect experience with the Automatic Updating option some further improvements might be needed:

A few KParts plugins have already seen such adaptions, like the SVGPart and the KUIViewerPart (see also blog post), adaptions to be released with KDE Applications 17.12.
Another KParts plugin has been written with that in mind from the start, the KMarkdownWebViewPart (see also blog post), which already has been released.

You might want to take some guidance by the respective commit “Support loading by stream and restoring state on reload” to the SVGPart repository.

Advertisements

KMarkdownWebView 0.2.0

KMarkdownWebView 0.2.0 has been released.

The KMarkdownWebView software is for the rendered display of Markdown documents, using web technologies (native wrapper around a webpage with a JavaScript library which creates HTML from the plain text handed in).
The software contains

  • a KParts plugin for rendered display of Markdown files, which enables KParts-using applications (like the archiving tool Ark or the file manager Krusader) to show Markdown files in the target format.
  • a Markdown file KIO thumbnail generator plugin, which allows KIO-powered file managers & dialogs to show thumbnails and previews of files in Markdown format in the target format (currently only available when building against QtWebKit)

The KMarkdownWebView KParts plugin is also prepared for best experience with the KTextEditor Document Preview plugin for KTextEditor-based applications like the editor Kate and IDE KDevelop.

KMarkdownWebView can be built both with QtWebEngine (preferred by the build system) and QtWebKit. Pass -DUSE_QTWEBKIT=TRUE to CMake to enforce the use of QtWebKit.

Download from: https://download.kde.org/stable/kmarkdownwebview/0.2.0/src/

sha256: c5a73c02bd2761d1786b080148e465ef69e4686d17e6adfc047350f36e7f6b16 kmarkdownwebview-0.2.0.tar.xz

Signed with my new PGP key
E191 FD5B E6F4 6870 F09E 82B2 024E 7FB4 3D01 5474
Friedrich W. H. Kossebau
kmarkdownwebview-0.2.0.tar.xz.sig

Changes since 0.1.0

  • Markdown KIO thumbnail generator plugin added (only with QtWebKit)
  • KParts plugin: offers actions “Select All” and “Copy Text” in more places
  • KParts plugin: fixed inverted logic on text selection in context menu with QtWebEngine
  • KParts plugin: fixed install location of metadata desktop file

KTextEditorPreviewPlugin 0.1.0

KTextEditorPreviewPlugin 0.1.0 has been released.

The KTextEditorPreviewPlugin software provides the KTextEditor Document Preview Plugin, a plugin for the editor Kate, the IDE KDevelop, or other software using the KTextEditor framework.

The plugin enables a live preview of the currently edited text document in the final format. For the display it uses the KParts plugin which is currently selected as the preferred one for the MIME type of the document. If there is no matching KParts plugin, no preview is possible.

Download from:
https://download.kde.org/stable/ktexteditorpreviewplugin/0.1.0/src

sha256:
21e17a97fe2b942991ce564371ce822564397488847f8d21d7d5b24d4c120796 ktexteditorpreviewplugin-0.1.0.tar.xz

Signed with my new PGP key
E191 FD5B E6F4 6870 F09E 82B2 024E 7FB4 3D01 5474
Friedrich W. H. Kossebau <kossebau@kde.org>
ktexteditorpreviewplugin-0.1.0.tar.xz.sig

Notes

Long term the plan is to merge this plugin into the Kate repository, or some new separate KTextEditor-Plugins repo, ideally already for KDE Applications 17.12.

For now though this plugin is in its own repository to allow an initial independent quick release cycle phase, following the release-often-and-early mantra. With the help of your feedback (file your issue) that should make the features of the plugin the ones you like to have rather soon.

Developers: Improve your favourite KParts plugin

While a usual KParts plugin works out of the box, for a perfect experience with the Automatic Updating option some further improvements might be needed:

A few KParts plugins have already seen such adaptions, like the SVGPart and the KUIViewerPart (see also blog post), adaptions to be released with KDE Applications 17.12.
Another KParts plugin has been written with that in mind from the start, the KMarkdownWebViewPart (see also blog post), which already has been released.

You might want to take some guidance by the respective commit “Support loading by stream and restoring state on reload” to the SVGPart repository.

KMarkdownWebView 0.1.0

KMarkdownWebView 0.1.0 has been released.

The KMarkdownWebView software provides a KParts plugin for rendered display of Markdown files, using web technologies (webpage with JavaScript library which creates HTML from the plaintext handed in). This enables KParts-using applications (like the archiving tool Ark or the file manager Krusader) to show Markdown files in the target format. It is also prepared for the upcoming “Live Preview” plugin for KTextEditor-based applications like the editors/IDEs Kate & KDevelop (see introduction).

The separate library libKMarkdownWebView is done for sharing code with a future Markdown thumbnailer plugin, whose code is not yet committed to the repository.

KMarkdownWebView can be built both with QtWebEngine (preferred by buildsystem) and QtWebKit. Pass -DUSE_QTWEBKIT=TRUE to CMake to enforce the use of QtWebKit.

Download from: https://download.kde.org/stable/kmarkdownwebview/0.1.0/src/

sha256: 361fec6c4fa9396975e788cfe759b1c45a2ccfc2b83e64b5105869ef312a5410 kmarkdownwebview-0.1.0.tar.xz

Notes

The technology behind KMarkdownWebView could be considered rather a hack, to quickly solve the need for rendering Markdown files, with the following requirements in mind:

  • webpage-like layouting (single page adapting width to screen/window size)
  • chrome-less minimalistic UI
  • support of KParts stream API (as useful with “Live Preview” plugin for KTextEditor)

Ideally this would be implemented one day natively in Qt by e.g. using QTextDocument & friends. The Markdown Okular generator gets us already closer to this, but misses all those bullet-points for now.

In-pane preview of Qt UI files with KUIViewer coming up

The “Live Preview” plugin for the editors/IDEs Kate & KDevelop (see introduction) makes use of KParts plugins to support different file formats. Thus it can also pick up the range of existing KParts implementations out there right from the start.

A perfect user experience with the “Live Preview” plugin means:

  • automatic updates of the preview while one edits the sources, without a reset of the preview settings (scroll position, zoom state, etc.)
  • not going through the file system to push changes in the sources to the preview

For that usually some more work needs to be done to the existing KParts plugins.

Editing in the Qt UI file worlds

One of those plugins, where I also have personal interest in and thus giving priority, is the KParts plugin from the KUIViewer, a tool to display and check Qt user interface (*.ui) files. Because in the recent time I have edited Qt UI files quite often and started to do this manually directly in the XML-based sources instead of in Qt Designer, as it became quicker to do for me the more I had learned the syntax. But for checking the current state I still had to save the file and load it separately in Designer or KUIViewer.

So the KUIViewer KParts plugin and the “Live Preview” plugin for KDevelop have started to improve my developer life 🙂

“Containers” for the rescue, once more

Besides some pain points though: if you used KUIViewer yourself before, you might remember that its code was operating straight forward. For one it instantiated any UI file as-is, e.g. showed a QMainWindow-based UI also as normal separate window in the workspace, so not embedded in the window of KUIViewer itself. Which comes at least as surprise, if not as something unhandy. Especially for the use with the “Live Preview” plugin, where the automatic update of the preview and thus the reloading of the UI file in the KUIViewer code means windows coming and going all the time.
Then normal widgets were shown as main widget of the KUIViewer window, which for very big or very small widgets result in according changes to the window and broken display in the “Live Preview” plugin.

Too much pain, and then I was looking at the sources anyway. So while extending the KUIViewer KParts plugin to implement the streaming API and restoring/keeping the view state on reloading from the same URL, I also reached out for the class QMdiArea for the rescue and changed KUIViewer to show the object defined by a UI file as a subwindow instead. And that way allowing widgets to have any sizes, but also taming QMainWindow-based UI to not escape the KUIViewer scene:

This change will be coming to everyone as part of KDE Applications 17.12.

And thanks to the respective code being in the KUIViewer KParts plugin, without any further changes we get the same tamed behaviour in the “Live Preview” plugin:

Improve your favourite KParts plugin for the “Live Preview”

If you edit some other sources often and want to be supported by the “Live Preview” plugin, get and build the plugin quickly yourself, the current state works good enough.
Then see if there is a matching KParts plugin you then can improve as needed.

The “Live Preview” plugin is currently planned to be released as official part of KDE Applications 17.12 and later as well, possibly as part of the Kate repo. So a few months left to shape up your favourite KParts plugin. Go for it now to be done in time 🙂

Look what you have done^W^Wdo!

You are using Kate or KDevelop and often editing directly the sources of Markdown files, Qt UI files, SVG files, Dot graph files and whatever else formats which are based on plain text files?

And you are having to use a workflow to check the current state which is saving the file and (re)loading it in a separate viewer application?

Could be better, right? Perhaps like this:

Nice mock-up. Or is it? Seems not! So, KParts-based preview plugin for Kate & KDevelop coming soon near you to a well-stocked package repository? Read the whole story where things are heading.

And a Markdown kpart? Never seen before. Because it is new. Actually seems the week of Markdown in the KDE community, there is also a patch on review to add Markdown support for Okular. Sadly Markdown support in Okular with the Okular kpart would not yet replace that separate Markdown kpart, because Okular does not support webview-style display (single “reactive” page), misses support for data streaming without touching the filesystem, and has too much chrome in the kpart for simple usage. Hope is on the future and somebody (you?) improving that. I am doing my share of improving things with this preview plugin, so I am out 🙂

Adding API dox QCH files generation to KDE Frameworks builds

Or: Tying loose ends where some are slightly too short yet.

When

  • you favour offline documentation (not only due to nice integration with IDEs like KDevelop),
  • develop code using KDE Frameworks or other Qt-based libraries,
  • you know all the KF5 libraries have seen many people taking care for API documentation in the code over all the years,
  • and you had read about doxygen’s capability to create API dox in QCH format,
  • and you want your Linux distribution package management to automatically deliver the latest version of the documentation (resp. QCH files) together with the KDE Frameworks libraries and headers (and ideally same for other Qt-based libraries),

the idea is easy derived to just extend the libraries’ buildsystem to also spit out QCH files during the package builds.

It’s all prepared, can ship next week, latest!!1

Which would just be a simple additional target and command, invoking doxygen with some proper configuration file. Right? So simple, you wonder why no-one had done it yet 🙂

Some initial challenge seems quickly handled, which is even more encouraging:
for proper documentation one also wants cross-linking to documentation of things used in the API which are from other libraries, e.g. base classes and types. Which requires to pass to doxygen the list of those other documentations together with a set of parameters, to generate proper qthelp:// urls or to copy over documentation for things like inherited methods.
Such listing gets very long especially for KDE Frameworks libraries in tier 3. And with indirect dependencies pulled into the API, on changes the list might get incomplete. Same with any other changes of the parameters for those other documentations.
So basically a similar situation to linking code libraries, which proposes to also give it a similar handling: placing the needed information with CMake config files of the targeted library, so whoever cross-links to the QCH file of that library can fetch the up-to-date information from there.

Things seemed to work okay on first tests, so last September a pull request was made to add some respective macro module to Extra-CMake-Modules to get things going and a blog post “Adding API dox generation to the build by CMake macros” was written.

This… works. You just need to prepare this. And ignore that.

Just, looking closer, lots of glitches popped up on the scene. Worse, even show stoppers made their introduction, at both ends of the process pipe:
At generation side doxygen turned out to have bitrotted for QCH creation, possibly due to lack of use? Time to sacrifice to the Powers of FLOSS, and git clone the sources and poke around to see what is broken and how to fix it. Some time and an accepted pull request later the biggest issue (some content missed to be added to the QCH file) was initially handled, just yet needed to also get out as released version (which it now is since some months).
At consumption side Qt Assistant and Qt Creator turned to be no longer able to properly show QCH files with JavaScript and other HTML5 content, due to QWebKit having been deprecated/dropped and both apps in many distributions now only using QTextBrowser for rendering the documentation pages. And not everyone is using KDevelop and its documentation browser, which uses QWebKit or, in master branch, favours QWebEngine if present.
Which means, an investment into QCH files from doxygen would only be interesting to a small audience. Myself currently without resources and interest to mess around with Qt help engine sources, looks with hope on the resurrection of QWebKit as well as the patch for a QtWebEngine based help engine (if you are Qt-involved, please help and push that patch some more!)

Finally kicking off the production cycle

Not properly working tools, nothing trying to use the tools on bigger scale… classical self-blocking state. So time to break this up and get some momentum into, by tying first things together where possible and enabling the generation of QCH files during builds of the KDE Frameworks libraries.

And thus to current master branches (which will become v5.36 in July) there has been now added for one to Extra-CMake-Modules the new module ECMAddQch and then to all of the KDE Frameworks libraries with public C++ API the option to generate QCH files with the API documentation, on passing -DBUILD_QCH=ON to cmake. If also having passed -DKDE_INSTALL_USE_QT_SYS_PATHS=ON (or installing to same prefix as Qt), the generated QCH files will be installed to places where Qt Assistant and Qt Creator even automatically pick them up and include them as expected:

Qt Assistant with lots of KF5 API dox

KDevelop picks them up as well, but needs some manual reconfiguration to do so.

(And of course ECMAddQch is designed to be useful for non-KF5 libraries as well, give it a try once you got hold of it!)

You and getting rid of the remaining obstacles

So while for some setups the generated QCH file of the KDE Frameworks already are useful (I use them since some weeks for e.g. KDevelop development, in KDevelop), for many they still have to become that. Which will take some more time and ideally contributions also from others, including Doxygen and Qt Help engine maintainers.

Here a list of related reported Doxygen bugs:

  • 773693 – Generated QCH files are missing dynsections.js & jquery.js, result in broken display (fixed for v1.8.13 by patch)
  • 773715 – Enabling QCH files without any JavaScript, for viewers without such support
  • 783759 – PERL_PATH config option: when is this needed? Still used?
  • 783762 – QCH files: “Namespaces” or “Files” in the navigation tree get “The page could not be found” (proposed patch)
  • 783768 – QCH files: classes & their constructors get conflicting keyword handling< (proposed patch)
  • YETTOFILE – doxygen tag files contain origin paths for “file”, leaking info and perhaps is an issue with reproducible builds

And some related reported Qt issues:

  • QTBUG-60933 – No qtdbus.tags file generated
  • QTBUG-61790 – Doxygen tag files have invalid data for enum types and values

There is also one related reported CMake issue:

  • 16990 – Wanted: Import support for custom targets (extra bonus: also export support)

And again, it would be also good to see the patch for a QtWebEngine based help engine getting more feedback and pushing by qualified people. And have distributions doing efforts to provide Qt Assistant and Qt Creator with *Web*-based documentation engines (see e.g. bug filed with openSUSE).

May the future be bright^Wdocumented

I am happy to see that Gentoo & FreeBSD packagers have already started to look into extending their KDE Frameworks packaging with generated API dox QCH files for the upcoming 5.36.0 release in July, with other packagers planning to do so soon as well.

So perhaps one not too distant day it will be just normal business to have QCH files with API documentation provided by your distribution not just for the Qt libraries itself, but also for every library based on them. After all documentation has been one of the things making Qt so attractive. As developer of Qt-based software, I very much look forward to that day 🙂

Next stop then: QML API documentation :/