Help manual needs to be included under Help menu

[jw3]

We need an offline copy of the user manual.

1. Maintain the docs as the GitHub Wiki
2. During RPM CI builds we clone the Wiki and build the User Guide section Markdown into HTML
3. Bundle the HTML as the doc
4. Have a placeholder HTML for non-RPM (like dev env) that just has a link to the Wiki

[dorschs57]

I've done some digging into how meld handles their help docs. They are using a markup language called Mallard that they are then converting to static HTML pages. These HTML pages are installed into /usr/share/help with the rpm install. When the menu option is activated they use Gtk.show_uri(Gdk.Screen.get_default(), "help:meld", Gtk.get_current_event_time()) to open the OS default help viewer and load their index.html page.

Expanding our @jw3 approach above we'd do something like:

1. Maintain the docs as the GitHub Wiki
2. During RPM CI builds we clone the Wiki and build the User Guide section Markdown into static HTML pages
3. On rpm install we'd install them to /usr/share/help/fapolicy-analyzer
4. In the UI add a help menu item that displays the help with the Gtk.show_uri_for_window command. This could have a fallback to the URL for the online Wiki help if the static pages are not available. This is how meld handles it.

I'll have to do some research on how to handle step 2. It would be nice to maintain the help docs in a single place like the Wiki. This might prove difficult thought if we want to support multiple languages. Meld handles this with po files. In a worst case scenario, Mallard has a project called DuckType that is a markdown like language for writing source. This can then be converted to static HTML pages. See their site for more details.

Also see:
https://book.huihoo.com/gtk+-gnome-application-development/sec-help.html
https://book.huihoo.com/gtk+-gnome-application-development/z72.html#SEC-INSTALLDOCS

Thoughts?

[jw3]

Internationalization trumps the benefits of wiki use. I'm good with pursuing mallard.

I had perused meld's docs previously and mistook mallard for html.

[dorschs57]

I did some digging into using the online wiki markdown files as our help documentation. It would be possible to pull our markdown docs at build time from the wiki repo and convert them to HTML5 with something like pandoc. I've run some tests with this and the conversion works and the itstool is able to generate the pot and po files from the html files for internationalization. However the show stopper here seems to be a bug in yelp that prevents it from displaying HTML docs. This bug is fixed in later releases of the app 3.36 and up. However on my RHEL 8 dev box I only have 3.28 available. See https://gitlab.gnome.org/GNOME/yelp/-/issues/158 for info about the bug.

Do we want to continue to pursue this route? We'll probably have to come up with some other viewer. Maybe we can render the HTML pages in the users default browser? Another option might be to reverse the process and maintain our help code as Mallard. We should be able to convert Mallard to HTML with yelp-tools and then from HTML to markdown with pandoc. After conversion the markdown could be committed to our wiki repo for use on the website.

[jw3]

Do we want to continue to pursue this route?

Let's stay with it for now.

What about HTML to Mallard?

Wiki Markdown => HTML => Mallard

Another option might be to reverse the process and maintain our help code as Mallard.

Perhaps.

Another option might be to bundle our own Yelp with the patch.

[dorschs57]

I have yet to find anything for translating HTML to Mallard. However I might have a solution. I can convert our markdown files to the docbook XML format. Docbook is also supported by yelp. I tested it on the older version I have on my dev machine and it will open the document. I'm going to go down this path a bit and see if it gets us to where we want.

@jw3 do you see an issue getting pandoc into our build pipeline? The rpm appears to be available in EPEL for RHEL 9 and Fedora 36/35 https://pkgs.org/search/?q=pandoc.

[jw3]

The pipeline will be ok.