PS: As far as KDE is concerned, khelpcenter's format would be fine too. But what about users using something else?

Yep, this is being discussed extensively.  The problem is khelpcenter doesn't support the same formats as found in Yelp, and vice versa (html versus xml).

Upstream there is work on coming up with a common format among all desktops (not just KDE).  Hopefully this will make it easier for us to produce a common file that is useful to all users.

I've been trying to understand what is up with the khelpcenter format.  Like a lot of KDE stuff, there seems to be very little -useful- documentation.  Interestingly, if I try to feed khelpcenter some XML (including a KDE doctype), khelpcenter comes up, then launches the xml document in a yelp window.  Other than the doctype, I haven't seen anything unusual in the khelpcenter xml format, but it seems to prefer using yelp to display xml.

KHelpCenter uses .docbook extensions for its files, not .xml.

That was one of the first things I picked up on, but whether you call it a .xml or .docbook, it opens in yelp.

KHelpCenter expects the documentation in subdirectories of /usr/share/doc/HTML/en/ (or the code of the language, but it'll fallback to en if there's no translated version). The "HTML" part there is really a misnomer as the documentation is actually .docbook files. There must be a /usr/share/doc/HTML/en/name-of-the-guidebook/index.docbook file. KDE documentations normally also ship an index.cache.bz2 file (which AFAIK contains pregenerated HTML), I'm not sure whether this is required or not.

(In reply to comment #6)
> KHelpCenter expects the documentation in subdirectories of
> /usr/share/doc/HTML/en/ (or the code of the language, but it'll fallback to en
> if there's no translated version). The "HTML" part there is really a misnomer
> as the documentation is actually .docbook files. There must be a
> /usr/share/doc/HTML/en/name-of-the-guidebook/index.docbook file. KDE
> documentations normally also ship an index.cache.bz2 file (which AFAIK contains
> pregenerated HTML), I'm not sure whether this is required or not.  

What is a .docbook file?  Is it XML?

It's XML with a "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" DTD.

Okay...  so our files are XML with a "<!DOCTYPE Book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd""  

So that should work.

I obviously tried most of those variants.

My first attempt was to add About_Fedora (a pretty simple document), to index.docbook.  Got nowhere with that, although in a number of gyrations mostly khelpcenter ignored my edits, sometimes it crashed.

Then I tried copying About_Fedora into help center's directory tree.  No joy there, either.  In that process, I also tried flattening About_Fedora and purging anything that looked a little Gnome-like from the xml, no joy either.

When I tried explicitly opening About_Fedora.xml with khelpcenter from the command line, khelpcenter opened and a second later About_Fedora opened in a Yelp window.

Then I noticed the KDE doctype, changed it, and got the same result.

Then I renamed About_Fedora.xml to About_Fedora.docbook (by now it is a terribly stripped-down About_Fedora), same result.

Unfortunately, my KDE VM is a little messed up so I can't easily test in a clean KDE environment.  All of this is happening on a full Fedora installation that has all sorts of KDE baggage as a result of needing Piklab.  It could be that without Yelp, khelpcenter would read it, but I can't easily test that.

So this is blocking F13 release, but seems stale - hasn't been touched since December. Can you get together and establish what the current situation is, and if there's a way to fix it for F13 final? Thanks.



-- 
Fedora Bugzappers volunteer triage team
https://fedoraproject.org/wiki/BugZappers

(In reply to comment #11)
> So this is blocking F13 release

WHAT??????

I tested the F13 Release Notes on F13 Alpha with GNOME, KDE and XFCE.

This HAS NOT bee fixed for F12 (hence not closed), but it is not relevant to F13 where the Release Notes are delivered in a different fashion.

There is no reason for this to be an F13 blocker.

calm down :) it was set to block f13 in december, I guess it wasn't clear at that point how this would be resolved.



-- 
Fedora Bugzappers volunteer triage team
https://fedoraproject.org/wiki/BugZappers

Created attachment 407175 [details]
Release Notes on KDE menu

There is actually a problem here on the F13 image, but it has been corrected.

Created attachment 407176 [details]
Release notes on KDE Live

hmmm, I guess I have to submit my comments before attaching ...

I probably saw that blocker back in December, but then F13 was impossibly far off.

But you reminded me that I hadn't checked it on the Beta (although I had checked a couple of the nightly composes), so I put the KDE Live on a stick and all works as expected (see pictures).

For the terminally curious, the Release Notes are now provided in HTML instead of XML.  The language selection is handled through Javascript.  There is a non-Javascript portion too, so non-JS users can still read the Release Notes, but they have to manually select their language.

I have since learned that Yelp is fully capable of rendering HTML as well, so in a future update I hope to provide the files that allow the display of the Release Notes in Yelp as before, without having to provide duplicate copies of the entire document.  The Release Notes are getting rather long, and are translated into many languages, so the footprint is quite large.  We made some headway on F13 by separating out the "All Changes" table into a separate document that isn't installed, but still, duplicating the entire content seems an excessive use of disk.

Corrected in F13