KMarkdownWebView 0.1.0

KMarkdownWebView 0.1.0 has been released.

Example: KMarkdownWebView KParts plugin used by Ark

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.

Advertisements

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

Give us a proper mimetype name for OpenCL C files!

KDevelop, your cross-platform IDE, since version 5.1 has initial OpenCL language support.

If you are into OpenCL and interested, we need your help for some improvement to that:

What is the mimetype name to use for OpenCL C files?

Due to KDevelop needs some weeks ago a mimetype for OpenCL has already been added to the shared-mime-info database, with text/x-opencl-src as mimetype name.
Though if we reflect, that entry was quickly requested and made without consulting a lot of OpenCL users. It currently reads:

<mime-type type="text/x-opencl-src">
    <_comment>OpenCL source code</_comment>
    <acronym>OpenCL</acronym>
    <expanded-acronym>Open Computing Language</expanded-acronym>
    <sub-class-of type="text/x-csrc"/>
    <glob pattern="*.cl"/>
</mime-type>

For one, “OpenCL source code” should be rather “OpenCL C source code”. Because there are now both C and C++ variants (see below) which would need to be reflected in the name.

Next, text/x-opencl-src was made up and seems to be not used by anyone before. Asking your search engine, you will see that people in their desperation had already started to use all kind of other mimetype names before, e.g.:

  • text/x-opencl
  • text/x-clsrc
  • text/x-opencl_c
  • application/x-opencl_c

So text/x-opencl-src might not have been the best choice. Even more as again the C and C++ variants need to be reflected in the name.

Is there no-one at the Khronos Group who had time to look at deciding on a mimetype name and registering that with IANA as MIME type (or now Media type)?

Can you poke them, or hint us whom to talk to?

OpenCL C++

And then there is OpenCL C++ (since OpenCL 2.1), yet to reach the masses.
What mimetype name shall it have? What will the file extension(s) be?

Wanted: your wishes on managing author identity data in KDevelop

If you are a software developer who likes IDEs, please help to shape a new feature that is currently worked on for KDevelop, your attractive cross-platform IDE for currently C, C++, Python, JavaScript and PHP:

support for management of multiple author identities (name, email, …)

Please help by telling your user stories around data about your author identity in your development process. Add the things you would like to see supported (soon or one day) here:
https://community.kde.org/KDevelop/AuthorIdentities#User_stories

Other contributions to that page are welcome, too. It is a wiki 🙂
(If a wiki scares you, replying in the comments to this blog post is also fine, everything will be picked up.)

To give you an idea what kind of things are wanted, read on:

Some initial user stories

Do not get in the way:

As developer working alone on a private project, I do not want to have to deal with any identity stuff, any defaults are fine with me.

Multiple identities in same system:

As developer working with the same computer/system on different projects for different customers or different project groups, I want KDevelop to always inject the correct/matching copyright & author information on generating code from file & app templates for different projects/customers, instead of having to manually post-edit the generated code.

Multiple identities in same project:

As developer working on the same project with the same computer system both for job and privately, I want to quickly switch identity data to be used depending on whether I work for job or privately, to mark copyright of contributions accordingly.

Pick up identity on import:

As developer importing a project into KDevelop, I want to have the identity automatically derived from account/server/fetched project and have the option to create a new identity from the found data if there is none, or overwrite with an existing identity.

Highlight my contributions in VCS history:

As developer working on a project with VCS support, I want my easily see my own commits in the vcs history, e.g. by being highlighted.

Update existing identity data:

As developer working on a project, I want to have assistance when identity properties had been changed (like email address or name) and this should be reflected in all existing copyright/contributor notions of a project, where possible.

Following some more background info why work has been started on this feature:

Problem

When it comes to copyright notions in code/files and authorship/committer id in version control systems, the name and the contact information, like email address, can be a few different ones for oneself. E.g. when working in different FLOSS projects, with each email address dedicated to the project, or when working on a FLOSS project both in name of an employer, but also privately in free times.

Currently KDevelop is hard-coded to use whatever is set for the default profile of KEMailSettings when generating new code from file templates, the only place right now using authorship metadata. KMail, the well-known email client, seems to be feeding KEMailSettings via the KIdentityManagement module, but otherwise there might be no data in there. So the developer has to manually complete the fields in the generated code.

The integration of KDevelop with git also ignores the author and commiter metadata used by git for the repo. They need to be set manually and are nowhere linked to what KDevelop knows.

For a truely integrated development experience this needs to be improved.

Solution

KDevelop could know about the concept of author identity, could allow to have multiple identities available to select from for a project, and could allow plugins to make use of identity details e.g. on doing VCS commits or generating code.

Here a screenshot of some proof-of-concept code:
Draft of KDevelop settings: Configure Author Identitites

So, what do you also think in general? Anything related which is worth looking
into for this? Other comments?

Marble in your CMake or qmake based project, now more easy

Marble, the virtual globe and world atlas, at its core is a library intended for reuse, libmarblewidget. This library is done with minimal dependencies to ease usage (e.g. just needs a few Qt5 modules).

The new version of Marble, coming with libmarblewidget v0.26 and released as part of KDE Applications 16.12, is now making it more easy to integrate libmarblewidget in your own software project, when using CMake or qmake as buildsystem.

To link your project to libmarblewidget and find its headers, you can have that in 1-2 lines:

For qmake a qt_Marble.pri file is installed. So in the pro file of your project just add:

QT += Marble

For this to work you have to do one out of these:

  • install Marble into the same prefix as your Qt5 installation (e.g. /usr)
  • pass -DMARBLE_PRI_INSTALL_USE_QT_SYS_PATHS=ON to cmake when building Marble
  • use the environment variable QMAKEPATH to point to the installation prefix of Marble when calling qmake on your project

For CMake some CMake config files are installed. So in the CMakeLists.txt of your project just add:

find_package(Marble REQUIRED)
target_link_libraries(my_project  Marble)

No more need for some own FindMarble.cmake file.

The CMake variant is already possible since libmarblewidget v0.25 (part of KDE Applications 16.08).

Learn more about how to use Marble in your project, e.g. by simple examples, at marble.kde.org.