User manual

[mariobl]

Hello Graeme,

just tested the Sphnix framework. It works as expected. The German translations are updated, and all pages appear in German now.

Be patient; don't merge my pull request for now, it's only intended to have something to track the progress. Next days I will fill the manual with more real contents. Regarding screenshots -- is it OK to reuse those from the Tanglet homepage, or should I take new ones, based on Qt6? BTW, do you like to ship the manual with authentic screenshots from Win/Mac systems, for the respective target platforms? I'm afraid I can't provide those.

[gottcode]

Regarding screenshots -- is it OK to reuse those from the Tanglet homepage, or should I take new ones, based on Qt6? BTW, do you like to ship the manual with authentic screenshots from Win/Mac systems, for the respective target platforms? I'm afraid I can't provide those.

It would probably be a good idea to take new screenshots based on Qt 6. The ones on the website are out of date and based on Qt 4. I should really update those at some point. :) I also don't think there is a need to ship Windows or Mac screenshots.

[mariobl]

Sorry for the horrible delay… During the last weeks, I've imported and updated the old user manual of glabels-qt which is now also based on .rst files. Then I remembered that I actually wanted to write a user manual for Tanglet... Here ist it. The installation toolchain in this branch is not changed from qmake to cmake yet, so I can't test the whole workflow for the time being. Please review the contents; proposals for changes are welcome.

[mariobl]

I've improved the .rst markup by consistently using roles as in the Tetzle manual. I've copied conf.py from there, but the new settings regarding the :email: role are not honored yet...

[gottcode]

Thanks for working on this, and sorry for the delay in responding!

Because of the state of the world, I sadly need you to confirm that you did not use an LLM to make the user manual. I have a very firm no AI stance and I will not merge anything that involved an LLM.

With that out of the way, I do have notes!

Having an almost empty index page seems redundant to me, especially since the license statement is repeated on the credits page. Instead, is there a way to use the content of the introduction page for the index page and only have the copyright statement once at the end?

The KDE documentation usually puts the menubar overview last, which seems logical to me. If you are reading the docs, I would think the part that is most interesting is how to play the game, followed by how to configure the game.

Is it necessary to put the menu mnemonics in the docs? I like the formatting of the KDE interface overview, and they don't do that. They do put the keyboard shortcuts in, which makes sense to me.

I noticed that the screenshots don't show the plurals correctly (eg "4 letter(s)" instead of "4 letters"). Did you take a screenshot of a noninstalled version?

I'm not completely sold on sphinx, as I'm somewhat unhappy with the resulting HTML files (especially the unnecessary search JavaScript and all of the extra unsued files under "_static"). It works for now, so I think we should sort out all of the wording and screenshots first, and then I can figure out what to do from there. I might still end up using sphinx if I can make HTML files I am happy with. I will worry about fixing the toolchain once the content is settled.

I am considering adding a help manual window that just shows the help HTML files using the QTextBrowser widget (assuming I can make the HTML simple enough), so the text about switching your web browser might not be needed.

[mariobl]

Thanks for working on this, and sorry for the delay in responding!

Sorry for my delay, it was a few years.

Because of the state of the world, I sadly need you to confirm that you did not use an LLM to make the user manual. I have a very firm no AI stance and I will not merge anything that involved an LLM.

No, it is written in my humble English ;) I haven't used any AI or LLM tools.

With that out of the way, I do have notes!

Having an almost empty index page seems redundant to me, especially since the license statement is repeated on the credits page. Instead, is there a way to use the content of the introduction page for the index page and only have the copyright statement once at the end?

Of course, we can use the index page also for other contents than some links to other pages. And you are right, if we have an license declaration somewhere else in the manual, we don't need this on the index page.

The KDE documentation usually puts the menubar overview last, which seems logical to me. If you are reading the docs, I would think the part that is most interesting is how to play the game, followed by how to configure the game.

Yes, we can do so.

Is it necessary to put the menu mnemonics in the docs? I like the formatting of the KDE interface overview, and they don't do that. They do put the keyboard shortcuts in, which makes sense to me.

No. If we don't do so, we would also ease the pain for translators: less markup to consider and no need to figure out where to place the mnemonics for the appropriate language. In my first draft of the gLabels manual I wrote it without mnemonics, but the maintainer started to add them after merging. In my opinion, we don't need them really.

I noticed that the screenshots don't show the plurals correctly (eg "4 letter(s)" instead of "4 letters"). Did you take a screenshot of a noninstalled version?

No, I have used a RPM package from my Copr repo, v1.6.8. Regarding the Qt theme, is it OK for you to use the Oxygen theme? Or better use the more recent Breezy/Fusion themes?

I'm not completely sold on sphinx, as I'm somewhat unhappy with the resulting HTML files (especially the unnecessary search JavaScript and all of the extra unsued files under "_static"). It works for now, so I think we should sort out all of the wording and screenshots first, and then I can figure out what to do from there. I might still end up using sphinx if I can make HTML files I am happy with. I will worry about fixing the toolchain once the content is settled.

If you use Sphinx, you can simply create, for example, files for the native help viewers on Windows and macOS systems. I like the output so far; maybe the HTML theme could be changed, but this is rather cosmetic. However, I wouldn't insist on Sphinx, it's your choice.

I am considering adding a help manual window that just shows the help HTML files using the QTextBrowser widget (assuming I can make the HTML simple enough), so the text about switching your web browser might not be needed.

If you don't care about the help files for Windows and macOS (at least the latter can also produced from any HTML files), then we could use something completely different instead of Sphinx. As far as I remember, I proposed already Mallard which is used in GNOME. It produces a very nice, non-strictly-hierarchical, but more topic-based output. All we need are some CLI tools, no hardcoded GNOME dependencies. If you are interested in an example, please be patient for a week or so, then I could rewrite the existing material in Mallard so that you can get an idea of ​​it. Mallard produces rather simple HTML, and if it is simple enough for a simple Qt based HTML viewer widget, the better for us. And as a side effect, it's easier to handle then .rst (although XML needs more markup than RestructuredText) because all you need for user docs is built-in, no extra stuff to pull from Pypi (like the mentioned :email: thing).

[gottcode]

Thanks for working on this, and sorry for the delay in responding!

Sorry for my delay, it was a few years.

No worries! I had forgotten all about the user manual until now. :)

Because of the state of the world, I sadly need you to confirm that you did not use an LLM to make the user manual. I have a very firm no AI stance and I will not merge anything that involved an LLM.

No, it is written in my humble English ;) I haven't used any AI or LLM tools.

Glad to hear it!

Is it necessary to put the menu mnemonics in the docs? I like the formatting of the KDE interface overview, and they don't do that. They do put the keyboard shortcuts in, which makes sense to me.

No. If we don't do so, we would also ease the pain for translators: less markup to consider and no need to figure out where to place the mnemonics for the appropriate language. In my first draft of the gLabels manual I wrote it without mnemonics, but the maintainer started to add them after merging. In my opinion, we don't need them really.

I agree, let's leave the mnemonics out.

I noticed that the screenshots don't show the plurals correctly (eg "4 letter(s)" instead of "4 letters"). Did you take a screenshot of a noninstalled version?

No, I have used a RPM package from my Copr repo, v1.6.8. Regarding the Qt theme, is it OK for you to use the Oxygen theme? Or better use the more recent Breezy/Fusion themes?

I don't have strong opinions either way. I did eventually make new screenshots on my website, and for that I used the default Breeze icon and widget theme because I figured that is what they would look like for most users. For myself I still use Oxygen. Use whatever theme you prefer.

I'm not completely sold on sphinx, as I'm somewhat unhappy with the resulting HTML files (especially the unnecessary search JavaScript and all of the extra unsued files under "_static"). It works for now, so I think we should sort out all of the wording and screenshots first, and then I can figure out what to do from there. I might still end up using sphinx if I can make HTML files I am happy with. I will worry about fixing the toolchain once the content is settled.

If you use Sphinx, you can simply create, for example, files for the native help viewers on Windows and macOS systems. I like the output so far; maybe the HTML theme could be changed, but this is rather cosmetic. However, I wouldn't insist on Sphinx, it's your choice.

Huh. I hadn't planned on using the native help viewers on Windows or macOS; I was just going to pop up the same user manual dialog on all platforms.

I am considering adding a help manual window that just shows the help HTML files using the QTextBrowser widget (assuming I can make the HTML simple enough), so the text about switching your web browser might not be needed.

If you don't care about the help files for Windows and macOS (at least the latter can also produced from any HTML files), then we could use something completely different instead of Sphinx. As far as I remember, I proposed already Mallard which is used in GNOME. It produces a very nice, non-strictly-hierarchical, but more topic-based output. All we need are some CLI tools, no hardcoded GNOME dependencies. If you are interested in an example, please be patient for a week or so, then I could rewrite the existing material in Mallard so that you can get an idea of ​​it. Mallard produces rather simple HTML, and if it is simple enough for a simple Qt based HTML viewer widget, the better for us. And as a side effect, it's easier to handle then .rst (although XML needs more markup than RestructuredText) because all you need for user docs is built-in, no extra stuff to pull from Pypi (like the mentioned :email: thing).

I would be happy to see an example! Take as long as you need, I'm not in a rush.

I plan on storing the final translated HTML files in the repository as well (part of the reason I want them to be simple), and only regenerating them as needed. That way deployment on Windows and macOS just uses the files already created instead of having to figure out how to make it work with the build systems there.

[gottcode]

I just remembered that Qt added support for rendering Markdown to QTextEdit back in the Qt 5 era, and it even includes the GitHub flavor. It would be possible to write the documentation as Markdown files. I don't know if that would be easier or harder than what you are planning, but that is another option to consider.

[mariobl]

If you don't care about the help files for Windows and macOS (at least the latter can also produced from any HTML files), then we could use something completely different instead of Sphinx. As far as I remember, I proposed already Mallard which is used in GNOME. It produces a very nice, non-strictly-hierarchical, but more topic-based output. All we need are some CLI tools, no hardcoded GNOME dependencies. If you are interested in an example, please be patient for a week or so, then I could rewrite the existing material in Mallard so that you can get an idea of ​​it. Mallard produces rather simple HTML, and if it is simple enough for a simple Qt based HTML viewer widget, the better for us. And as a side effect, it's easier to handle then .rst (although XML needs more markup than RestructuredText) because all you need for user docs is built-in, no extra stuff to pull from Pypi (like the mentioned :email: thing).

I would be happy to see an example! Take as long as you need, I'm not in a rush.

See my latest commit. It's a quick conversion of the existing material, not perfect (for example, crossreferencing is still incomplete), but maybe good enough for a first look. To create the HTML pages, run mkdir -p html && yelp-build html -o html . (after installing yelp-tools if you don't have it).

I plan on storing the final translated HTML files in the repository as well (part of the reason I want them to be simple), and only regenerating them as needed. That way deployment on Windows and macOS just uses the files already created instead of having to figure out how to make it work with the build systems there.

As far as I can see, both Win and Mac build their user docs on HTML files; there's no special source format. But if you plan to use a Qt based viewer anyway, then nobody needs to bother with create anything special for proprietary OSes.

Another option would be Markdown. Easy to write, closer to plain text than Mallard – but it needs Pandoc for an acceptable HTML output. Pandoc is a big chunk (200 MB on Fedora) and quite slow… Some years ago, I've used it as part of a toolchain for Groff --> Asciidoctor conversion. But if it makes anything better, we could also think about it.

[gottcode]

If you don't care about the help files for Windows and macOS (at least the latter can also produced from any HTML files), then we could use something completely different instead of Sphinx. As far as I remember, I proposed already Mallard which is used in GNOME. It produces a very nice, non-strictly-hierarchical, but more topic-based output. All we need are some CLI tools, no hardcoded GNOME dependencies. If you are interested in an example, please be patient for a week or so, then I could rewrite the existing material in Mallard so that you can get an idea of ​​it. Mallard produces rather simple HTML, and if it is simple enough for a simple Qt based HTML viewer widget, the better for us. And as a side effect, it's easier to handle then .rst (although XML needs more markup than RestructuredText) because all you need for user docs is built-in, no extra stuff to pull from Pypi (like the mentioned :email: thing).

I would be happy to see an example! Take as long as you need, I'm not in a rush.

See my latest commit. It's a quick conversion of the existing material, not perfect (for example, crossreferencing is still incomplete), but maybe good enough for a first look. To create the HTML pages, run mkdir -p html && yelp-build html -o html . (after installing yelp-tools if you don't have it).

Mallard does make quite nice HTML files, and without the extra baggage Sphinx was adding! Sadly, Qt doesn't handle the CSS well, so they look kind of odd in QTextBrowser. I will play around with the CSS and see if there is a way to make them look better in Qt.

I plan on storing the final translated HTML files in the repository as well (part of the reason I want them to be simple), and only regenerating them as needed. That way deployment on Windows and macOS just uses the files already created instead of having to figure out how to make it work with the build systems there.

As far as I can see, both Win and Mac build their user docs on HTML files; there's no special source format. But if you plan to use a Qt based viewer anyway, then nobody needs to bother with create anything special for proprietary OSes.

Another option would be Markdown. Easy to write, closer to plain text than Mallard – but it needs Pandoc for an acceptable HTML output. Pandoc is a big chunk (200 MB on Fedora) and quite slow… Some years ago, I've used it as part of a toolchain for Groff --> Asciidoctor conversion. But if it makes anything better, we could also think about it.

Qt added support for reading Markdown directly a few years ago, so I wouldn't even need to run pandoc on them to make HTML files at all. I could just distribute the Markdown files with Tanglet.

[mariobl]

OK, if this works, and it renders properly including notes, pictures, tables and inline markup like menu entries and keystrokes, it would be the simplest solution. But we should keep translations in mind. Mallard is easy to translate thanks to its XML nature, but Markdown... However, the latest version of po4a comes with improved Markdown support, according to their release notes. Let me test it first.

[gottcode]

Am I overthinking things?

I was going to store the generated HTML files in the git repository so that I don't have to run anything on Windows, so maybe I should just manually remove the JavaScript from the Sphinx generated HTML files when I go to update the translations. I wouldn't have to integrate with the build system at all.

I do like the way the user manual generated by Sphinx looks in a web browser. It would be a lot simpler to just call the user's web browser than to write a help browser with QTextBrowser. And then I don't need to worry about QTextBrowser's limitations in rendering.

[mariobl]

OK, it's your choice. No matter what you use, as long as it is translatable in a painless manner. Sphinx produces nice and readable .po files, also Mallard does. No rush, better thinking twice than end up in too much maintenance work.

[mariobl]

From the PR in tetzle:

Please note, I've used the :email: role. To get this working with Sphinx, the extension sphinxcontrib-email is needed to produce HTML output. Because it was not packaged for my distribution (Fedora), I've installed it with pip install sphinxcontrib-email.

That isn't packaged for my distro either. Do there have to be email addresses? If you want, you could link to https://gottcode.org/ for my name, as I do have contact links on my website.

Maybe, but I think it's better to create canonical mailto: links instead of the redirection to the website. The mentioned pip command installs it under ~/.local/, so no worries about overwriting system files. If you are using Fedora, you can use my COPR repo to install it.

[mariobl]

Just tested the behavior of the resulting html files. Both Yelp an Khelpcenter can open index.html by submitting the file name on the command line.

In Yelp:

In Khelpcenter:

So we could use installed help viewers: First, try to open the help in Khelpcenter. Then try to find Yelp and open it there. Or swap Yelp and Khelpcenter, but we shouldn't force users to read it in the browser when a native help viewer is present. Last, merely as a fallback solution, open it in $BROWSER. And as I mentioned, Sphinx supports Applehelp directly, and I think I can also figure out a way to create native Windows help files (I have only an old Windows 10, but this should be sufficient for this task). In all of the cases, we need only the html files, maybe with a bit customized CSS.

All this assuming you want to stay with Sphinx – if not, no problem.

[mariobl]

Sphinx can't build Applehelp on Linux systems. It needs /usr/bin/hiutil, which is only available on native macOS systems; there no alternative for Linux. That's why cross-building under Linux is impossible :(

[gottcode]

So we could use installed help viewers: First, try to open the help in Khelpcenter. Then try to find Yelp and open it there. Or swap Yelp and Khelpcenter, but we shouldn't force users to read it in the browser when a native help viewer is present. Last, merely as a fallback solution, open it in $BROWSER. And as I mentioned, Sphinx supports Applehelp directly, and I think I can also figure out a way to create native Windows help files (I have only an old Windows 10, but this should be sufficient for this task). In all of the cases, we need only the html files, maybe with a bit customized CSS.

I don't see why it would be better? Other open source projects just use the user's web browser for the user manual (such as Inkscape or Scribus). I don't really want to add a bunch logic to call help viewers, since this is just HTML.

Sphinx can't build Applehelp on Linux systems. It needs /usr/bin/hiutil, which is only available on native macOS systems; there no alternative for Linux. That's why cross-building under Linux is impossible :(

I don't have a Mac, so I wouldn't have a way of testing any code for that. I don't make builds for the macOS anymore and I haven't supported it since 2020.

[mariobl]

I don't see why it would be better? Other open source projects just use the user's web browser for the user manual (such as Inkscape or Scribus). I don't really want to add a bunch logic to call help viewers, since this is just HTML.

In a help viewer, it looks better, especially in a smaller window, which doesn't cover all the others. But see below.

I played a bit with the Mallard version, added some things and rework the structure, and added new screenshots.

More bad news regarding the help viewers:

Yelp displays HTML files correctly; forth and back buttons are usable for navigation. But when opening a href link, it opens in the browser. but the user doesn't get a notification about it. This is not OK when an existing browser window is on another workspace. Installing the .page files under /usr/share/help/C could solve this problem, but I'm not happy with the effort for such a GNOME-only solution.

Khelpcenter also displays the files, but the forth and back toolbar buttons are grayed out. However, I can navigate between the pages using the arrow buttons on the page itself. This is not OK… Next problem arises when clicking on a href link. The external website opens in the khelpcenter windows, and because I don't have the HTML arrow buttons anymore, I can't go back to the help page. I haven't figured out yet how to create native KDE help files from HTML. Although installed in /usr/share/doc/HTML/, these files are actually docbook sources with some extra stuff for feeding the KDE help index.

Finally, I tested the behavior in browsers. I thought I can simulate a small html viewer by opening a new browser window in fixed size. Iget it with

$ google-chrome-stable --new-window --window-size="840,570" index.html &

but only when no other Google Chrome Window is open. In this case, the new window inherits the dimensions from the existing one. Anyway, Firefox opens the new window independently from the dimensions of an existing one. But I don't even want to know what it looks like in other browsers. It's impossible for us to accommodate everyone.

So actually we don't have any options when we stay on pre-built HTML files. It was my preferred solution because I find the HTML pages rendered from Mallard to be the best due to their non-hierarchical structure.

Finally, I've tested the Markdown module of the latest Po4a version for translations. It's far from being as mature as, for example, the Asciidoc and Groff/Mdoc modules, but translators can work with. Tables are displayed a bit complicated and ugly (we don't have many of them anyway), but still OK.

From my side, I treat the Mallard manual as fairly complete, please review. Whatever format you finally choose, let me know, I will convert it.

[mariobl]

But not to forget: Mallard would also easily be translatable using itstool or gettext directly.

[mariobl]

And last but not least, the Markdown version. It includes already a version translated into German (still incomplete).

I've used the Github syntax of Markdown. The local HTML creation using Pandoc was not what I had expected... So with this Markdown, we would need to use the text widget functions built in Qt (which obviously understand the Github extensions).