Open mariobl opened 6 years ago
jimevins
commented
6 years ago I haven't given it much thought yet. I was hoping that the pages could be maintained in markdown and converted to HTML. I would like to do more research as to what other Qt projects are doing.
mariobl
commented
6 years ago After having a deeper look at Qt apps and user manuals, I see that Qtassistant is not widely used. Qtikz, a Qt-only variation of the KDE Tikz editor, seems to be only one application outside Qt itself which uses it [1]. The project maintains the docs sources in DocBook, but I wouldn't switch back to that. But in any case, it's a working example for using the user help system in Qt.
However, the simplest way to move the existing user manual to the brave new Qt world, is keeping the Mallard format, tweaking the contents here and there and add new screenshots. Although yelp-tools (which creates the HTML files) seems to be Gnome-related, it doesn't have any Gnome or GTK dependencies. So we could keep Mallard and produce the HTML stuff at build time, or even while creating the release tarball. What's your opinion?
mariobl
commented
6 years ago Obviously there's no way built in Qt/Qtassistant to handle translated documentation. We will end up in a gettext based workflow, I think.
Just did a few tests with the current XML files. Normally po4a can read almost all known documentation formats, but it fails with Mallard. The manpage of po4a says that DocBook is fully supported, but it doesn't say anything about Mallard. Example from index.page:
msgid " The " msgstr ""
msgid "gLabels" msgstr ""
msgid "" " application is a lightweight program for creating labels and \n" " business cards for the GNOME desktop environment. It is designed to work with \n" " various laser/ink-jet peel-off label and business card sheets that you'll find \n" " at most office supply stores.\n" " " msgstr ""
Too many parts are splitted into too small strings, translators won't be happy... I think Mallard is unusable without using yelp-tools. In contrast to that, po4a works fine with Markdown, which will handled as plain text, keeping the tags intact. But with Markdown, we get lost of the topic based approach of the current gLabels user manual, it becomes static again like DocBook.
On the other hand, gLabels needs a new translation platform. I don't know where Mallard or Markdown are best supported. And finally, because Qtassistant probably doesn't support translated manuals, we will need our own documentation viewer. My coding skills are poor, actually non-existent, but I found a basic HTML viewer in Qt itself [1] which could be implemented as long as Qtassistant doesn't match our needs. Or we fall back to the ancients and use $XDG_BROWSER instead.
For clarification of the Qtassistant abilities, I've filed a bug report in Qt [2].
[1] https://doc.qt.io/qt-5.10/qtwebview-index.html [2] https://bugreports.qt.io/browse/QTBUG-68002
mariobl
commented
6 years ago My bug report for Qtlinguist, although rather a feature request, is now almost three months old. We shouldn't hope that something happens there. So it is the best way to use either $XDG_BROWSER or the already mentioned qtwebview, with a HTML manual without the peculiarities which Qtassistant requires.
jimevins
commented
6 years ago I agree that we want to generate straight unadulterated HTML. But what source format and toolchain should we use. Several months ago, I started to survey other Qt based projects. Unfortunately, I quickly ran out of steam. This is as far as I got (not very far):
https://github.com/jimevins/glabels-qt/wiki/Survey-of-Documentation-in-Qt-Applications
Since we are talking about HTML, the survey should not limit itself to only Qt projects.
mariobl
commented
6 years ago Let me summarize what I could imagine:
We keep the current Mallard based manual, fix it here and there and add new screenshots. We also keep the current workflow using itstool and yelp-tools. Although both seem to be close to Gnome and GTK, they don't have any dependencies to GTK stuff.
So we generate a *.pot template and let it translate. Existing translations can be reused, of course with many "fuzzy" strings, but much better for our contributors than writing a translation from scratch. After fetching the po files from Transifex/Weblate/Zanata/Whatever-we-want, we generate translated Mallard documents. Producing the HTML files can be done while creating the tarball, or better, downstream while installing Glabels or creating the binary package.
Currently we have no simple way to let Qtassistant handle localized user manuals, but maybe there is one: There's no builtin mechanism like in GTK, but if we let Qtassistant call the manual depending on the current locale... this would hopefully work. Qtassistant has the following options:
Usage: assistant [Options]
-collectionFile file Uses the specified collection file instead of the default one -showUrl url Shows the document with the url. -enableRemoteControl Enables Assistant to be remotely controlled. -show widget Shows the specified dockwidget which can be "contents", "index", "bookmarks" or "search". -activate widget Activates the specified dockwidget which can be "contents", "index", "bookmarks" or "search". -hide widget Hides the specified dockwidget which can be "contents", "index" "bookmarks" or "search". -register helpFile Registers the specified help file (.qch) in the given collection file. -unregister helpFile Unregisters the specified help file (.qch) from the give collection file. -setCurrentFilter filter Set the filter as the active filter. -remove-search-index Removes the full text search index. -rebuild-search-index Obsolete. Use -remove-search-index instead. Removes the full text search index. It will be rebuilt on next Assistant run. -quiet Does not display any error or status message. -help Displays this help.
The -showUrl option could be the solution for us.
mariobl
commented
6 years ago My bugreport for Qtassistant was more than three months ago, so I don't expect help from there. I've asked for suggestions in the Qt translator mainling list [1].
Just played a bit with the -showUrl option. It doesn't work on normal HTML files. Probably an already registered help file (*.qch) is needed. But let's wait for possible answers from that mailing list.
[1] http://lists.qt-project.org/pipermail/localization/2018-August/000463.html
jimevins
commented
5 years ago Over the last several months, I have been researching documentaion formats/toolchains for the user manual and man pages. These are my current notes and conclusions.
I would like to use a light-weight format such as markdown. I do not consider XML based formats to fit this bill. Some desired characteristics of such a format are:
Some formats that may fit this bill are:
There may be others that fit the bill, but these are the ones that I am currently aware of.
Markdown is the simplest and probably most widely used of these formats. However, it is not without its problems. Some of the problems with markdown is that the markup provides very little semantic meaning, there no single standard, and lack of extensibility. It is best suited for small single page documents. It is not really suited for more complex documents such as a multi-page hyperlinked user manual.
POD is comes from the Perl world and is used extensively there.
Asciidoc comes from the Python world. Asciidoctor is a later ruby implementation.
reST also comes from the Python world. reST is used extensively there, but it is also used extensively outside of this community, including by CMake, the Linux kernel, Krita, and many other projects, books, and websites.
Translations should be possible without having to completely re-write the
document, including all of its markup. 'po4a' seems to geared well to these
text based formats. 'sphinx' seems to have built-in support for
gettext catalogs. Unfortunately, in either case we have a separate
toolchain (and possibly different workflow) from the application's native
Qt translations.
Basically, I don't want to integrate the building of documentation and translations with the default build. The documentation tools should be an optional dependency. The documentation should be built as a separate target (checking in the results). An alternative might be to live in its own repository.
Although many of the potential tools may be portable to all/most supported platforms, this would add an additional burden for the builder/packager to locate and install these additional prerequisites. The resulting documentation HTML/PDF is pretty much universally portable, unlike executables.
Man pages should be considered separately from the "user manual". Man pages must be distributed with the source and executables. Most man pages are never translated, but if we build with the same documentation toolchain we won't have yet another translation toolchain/workflow.
Possible formats/tools:
At this point I am leaning towards sphinx/reST for both the "user manual" and man pages. It is actively being used and adopted by many projects. In the case of the Linux kernel, it has supplanted DocBook.
It natively supports gettext catalogs for i18n. I am not sure how easy it will be to accomodate its translation toolchain/workflow with our existing application translations.
Currently I am leaning towards creating help/ and man/ top-level
directories for the documentation source and output in the main
glabels-qt repository.
mariobl
commented
5 years ago The Python Sphinx approach for the man pages looks very promising for the time being. Once the internationalization and localization work as expected, I like to port the existing user manual to the "brave new world" ;) All I would need is a working build environment - possibly with some stub pages - which enables testing.
mariobl
commented
4 years ago Now I'm succeeded to create a suitable build environment. Next days I will start with porting the existing Mallard manual to RestructuredText.
jimevins
commented
4 years ago Please note, I started an outline at
mariobl
commented
4 years ago Please note, I started an outline at
OK, I will consider this.
mariobl
commented
4 years ago The framework for the user manual is available (using the outline in the Wiki), see my recent pull request. For the time being, it still contains Makefile and make.bat as generated by the sphinx-quickstart command. But I've no idea what to do to integrate this with CMakeLists.txt, moreover, I never did anything with build systems. Please have a look at it, and once it works with CMake, the mentioned plain Make stuff can be safely removed.
jimevins
commented
4 years ago I have merged your pull request #77 into a new branch called UserManual. I would like to hold-off merging with master until it is more mature.
In it, I have integrated sphinx into the optional user-docs target in the CMake build system. The following subordinate targets have been added to the optional user-docs target
I have also integrated the display of the qthelp documents from the help menu. The HTML manual is intended for an online version.
mariobl
commented
4 years ago Thanks! I will go ahead next days with filling the pages with real content.
Hello,
some years ago I've converted the gLabels user manual from DocBook to Mallard and made it translatable. Now gLabels will switch from GTK to Qt, and we will need a new approach. Keeping the Mallard structure and workflow as-is would be possible, but it would need yelp-tools from Gnome. Bad idea...
IMHO, the topic-based approach is much better in comparison with the rather static DocBook stuff. So my first idea was to simply convert the Mallard files to HTML using yelp-tools. HTML is the base for both Qtassistant and KDE help viewer. Then we have to think about translations... There's a tool named html2po [1]. Don't know if it is the best choice, because maintaining static HTML code is a lot of work. Maybe we have a Gnome-agnostic Mallard converter anywhere on the web, which would allow to keep the format and structure...? Pintail [2] could possibly solve this problem. Next time I'll have a look at it. But currently it is only packaged in Fedora, even from the Archlinux User Repository is no package available. But maybe it would allow to stay at Mallard and create the needed HTML files at build time.
[1] http://docs.translatehouse.org/projects/translate-toolkit/en/latest/commands/html2po.html [2] https://github.com/projectmallard/pintail
Best Regards, Mario