As it turns out, we're Doing It Wrong with the current structure of the built-in help. Instead of including a bunch of xmls opened directly and transforming xrefs to ulinks, we should keep xrefs and have a top-level index.docbook file linking everything together, and calling yelp help:anaconda/$id.
More info in comments below.
+++ This bug was initially created as a clone of Bug #1276226 +++
Description of problem:
I've encountered this while testing Fedora RC6 (Xfce Live).
In Anaconda, if I press the "Help" button, a blank window is shown. That window has only got the statement "URL cannot be shown".
Version-Release number of selected component (if applicable):
anaconda-23.19.10-1.fc23.i686
How reproducible:
Everytime I press "Help" on Xfce's liveinst
Steps to Reproduce:
1. Launch liveinst from the desktop's icon.
2. Press the "help" button.
Actual results:
As described above (see the attached screenshot).
Expected results:
Perhaps it's a normal behavior with Xfce's liveinst, but I think that a help page should be shown.
--- Additional comment from awilliam on 2015-10-29 03:26:38 EDT ---
Confirmed I see this also on Workstation live x86_64.
This creates a pretty bad impression, but doesn't obviously violate any criteria; still, it seems at least an FE, and we should probably talk it over at go/no-go. Nominating as blocker for that reason.
--- Additional comment from awilliam on 2015-10-29 03:27:40 EDT ---
FWIW, the button runs:
yelp /usr/share/anaconda/help/en-US/(SOMEFILE).xml
the file depends on the screen you're on. The locations it tries to open are correct and they appear to be valid XML files; I don't know why yelp is failing to open them. Trying a command like:
yelp file:///usr/share/anaconda/help/en-US/(SOMEFILE).xml
doesn't help, so that's not the problem.
--- Additional comment from awilliam on 2015-10-29 03:41:12 EDT ---
Downgrading to yelp 3.16.0 makes it work; it's clearly a yelp bug (or, maybe they'll say it's just an INCOMPATIBILITY, but yeah, whatever, yelp 3.17+ can't open the anaconda help files).
this has been broken since Alpha, great testing job by us! wooohoo go team.
--- Additional comment from awilliam on 2015-10-29 03:58:23 EDT ---
'URL cannot be shown' seems to be a webkit error message, but the bug definitely seems to be in yelp; just downgrading yelp without changing anything else makes it work. yelp must be passing a badly-formed URI to webkit, I guess.
--- Additional comment from Mike Ruckman on 2015-10-29 04:05:59 EDT ---
I've also seen this on the 32bit workstation.
--- Additional comment from awilliam on 2015-10-29 04:08:23 EDT ---
This can be reproduced with non-anaconda files - it seems opening any filesystem location with yelp just doesn't work any more. Also I narrowed down the point where it broke: between 3.17.2 and 3.17.3.
With yelp 3.17.2, 'yelp /usr/share/help/C/gedit/index.page' opens the gedit help. With 3.17.3 or later it gives the error. 'yelp help:gedit' works in both cases.
--- Additional comment from Matthew Miller on 2015-10-29 08:14:21 EDT ---
(In reply to awilliam from comment #3)
> Downgrading to yelp 3.16.0 makes it work; it's clearly a yelp bug (or, maybe
> they'll say it's just an INCOMPATIBILITY, but yeah, whatever, yelp 3.17+
> can't open the anaconda help files).
>
> this has been broken since Alpha, great testing job by us! wooohoo go team.
Not that this helps now, but is it something AutoQA can test for in the future?
--- Additional comment from awilliam on 2015-10-29 11:58:02 EDT ---
openQA. And, yeah, it could. Also any human could do it trivially, of course - but we don't have a test case for it, so apparently no-one did.
--- Additional comment from Matthias Clasen on 2015-10-29 12:42:10 EDT ---
Could we get anaconda to install its help files properly, and use
yelp help:anaconda
?
--- Additional comment from Matthias Clasen on 2015-10-29 13:51:09 EDT ---
sadly, I couldn't find any combination of moving and renaming that would
yelp help:anaconda
work with docbook. It would work if anaconda help was in mallard format.
Since all the other applications using yelp for its help display have been converted to use mallard, doing the same with the anaconda help would be a good idea for the future.
--- Additional comment from Shaun McCance on 2015-10-29 14:39:06 EDT ---
Untested but hopefully correct combination of moving and renaming that would allow access with help: URIs for DocBook:
1) Move all the (English) files to /usr/share/help/C/anaconda.
2) If there are translated docs, move them to /usr/share/help/{ll}/anaconda, replacing {ll} with the locale identifier.
3) Make sure the top-level DocBook file is called index.docbook, not index.xml or anaconda.xml or anything else.
The help scheme is format-neutral and relies on there being a file called index.{ext}, where {ext} indicates the format.
--- Additional comment from awilliam on 2015-10-29 14:45:44 EDT ---
anaconda doesn't have a top-level file, it's not structured that way. You're not supposed to navigate it exactly. What it has is a bunch of essentially independent pages, one for each screen of the installer; in the installer UI, each screen has a 'Help' button which should show the help page for that screen.
We have already tried moving the files to /usr/share/help/C/anaconda and doing stuff like this:
yelp help:anaconda/PageName
yelp help:anaconda:PageName
yelp help:anaconda/PageName.xml
yelp help:anaconda:PageName.xml
none of that works.
--- Additional comment from Matthias Clasen on 2015-10-29 14:48:21 EDT ---
(In reply to Shaun McCance from comment #11)
> Untested but hopefully correct combination of moving and renaming that would
> allow access with help: URIs for DocBook:
>
> 1) Move all the (English) files to /usr/share/help/C/anaconda.
>
> 2) If there are translated docs, move them to /usr/share/help/{ll}/anaconda,
> replacing {ll} with the locale identifier.
>
> 3) Make sure the top-level DocBook file is called index.docbook, not
> index.xml or anaconda.xml or anything else.
>
> The help scheme is format-neutral and relies on there being a file called
> index.{ext}, where {ext} indicates the format.
This was among the combinations I tried - it doesn't work.
--- Additional comment from Shaun McCance on 2015-10-29 14:57:58 EDT ---
I didn't realize the Anaconda docs were structured that way. Yelp expects there to be a single document that includes all the sections (either through XInclude or SYSTEM entities). Looking at it now, I see it's just a collection of sections that aren't included into a single document. You can add a book to hold them. I'm attaching an index.docbook file to use. Then you can use:
yelp help:anaconda
Or to access a particular section:
yelp help:anaconda/sect-installation-gui-manual-partitioning
Note that the page ID must be the id attribute of the section you want, not the base file name.
--- Additional comment from Shaun McCance on 2015-10-29 14:59 EDT ---
--- Additional comment from Matthias Clasen on 2015-10-29 15:04:01 EDT ---
oh, that actually works. Thanks, Shaun
--- Additional comment from awilliam on 2015-10-29 15:04:47 EDT ---
we'd still need to teach anaconda to open the section names, though. I don't know how hard that is.
--- Additional comment from Shaun McCance on 2015-10-29 15:11:08 EDT ---
You'll also need to change all the internal links to use the xref element instead of ulink. So, for example, line 51 of SummaryHub.xml has this:
<ulink url="ProgressHub.xml">Configuration and Installation Progress</ulink>
It would instead need to be:
<xref linkend="sect-installation-gui-installation-progress">Configuration and Installation Progress</xref>
Or, actually, since the link text is the same as the target title, just this:
<xref linkend="sect-installation-gui-installation-progress"/>
The linkend has to be the target id attribute, not base filename. (Life is easier when you make id attributes match filenames.)
Only do this to links within the Anaconda docs. The links to bugzilla.redhat.com, docs.fedoraproject.org, etc should stay as ulink elements.
--- Additional comment from awilliam on 2015-10-29 15:12:49 EDT ---
As an alternative, http://koji.fedoraproject.org/koji/taskinfo?taskID=11630626 is a scratch build of a downgraded yelp. I'm going to do a live image with that yelp now and see if things mostly still work.
--- Additional comment from Stephen Gallagher on 2015-10-29 15:18:09 EDT ---
(In reply to awilliam from comment #19)
> As an alternative,
> http://koji.fedoraproject.org/koji/taskinfo?taskID=11630626 is a scratch
> build of a downgraded yelp. I'm going to do a live image with that yelp now
> and see if things mostly still work.
FWIW, there are no obvious failures with this build and the file-paths work again. I'll continue to poke at it, but this is looking promising.
--- Additional comment from Matthew Miller on 2015-10-29 15:56:06 EDT ---
Cool, I'm glad that there's a way out. For what it's worth, there's a strong consensus among the marketing and press people I've spoken with that it'd be best to block on this.
--- Additional comment from awilliam on 2015-10-29 16:21:07 EDT ---
So, an update here. I scratch built yelp 3.17.2 with an epoch bump:
http://koji.fedoraproject.org/koji/taskinfo?taskID=11630626
and built a Workstation live with that yelp for testing. It displays anaconda's help correctly. I was also able to launch every app on the live image, open Help, and look around, and everything looked fine. I also tested searching and creating bookmarks.
I did see yelp crash on launch twice (out of 50-60 launches), but it didn't seem to be obviously reproducible, and that bug may be in 3.18 too, we likely haven't tested it that intensively either. I'll try and reproduce and file the crash next.
Dennis has to go out in ~40 minutes and that's probably our window for doing an RC10 with the downgraded yelp and not slipping a week. In theory we should not respin for a non-blocker issue, but I think we can reasonably consider it for this issue as a special case, since there seems to be a lot of concern about it.
So, to have a formal record, can anyone who would be in favour of spinning an RC10 with the downgraded yelp say so here?
As an alternative we could accept the release criterion I proposed a couple of hours ago on test@ as an F23 criterion, which would make this issue a release blocker and require that we either fix it today or slip; it would preclude releasing with this broken.
--- Additional comment from Stephen Gallagher on 2015-10-29 16:25:01 EDT ---
I'm in favor of doing the build tonight and deciding tomorrow at Go/No-Go which build to take (or whether to slip if this build fails).
--- Additional comment from Dan Mossor [danofsatx] on 2015-10-29 16:36:05 EDT ---
I'm in favor of RC10 to fix the yelp issue. This is an obvious "First Stop" application for new users that get confused in anaconda. Yeah, it still happens.
--- Additional comment from Mike Ruckman on 2015-10-29 16:36:53 EDT ---
I am +1 to this plan.
--- Additional comment from Kevin Fenzi on 2015-10-29 16:37:28 EDT ---
+1 to spin a rc10 for just this FE and we decide tomorrow which to go with.
--- Additional comment from Giulio 'juliuxpigface' on 2015-10-29 16:40:28 EDT ---
(In reply to Stephen Gallagher from comment #23)
> I'm in favor of doing the build tonight and deciding tomorrow at Go/No-Go
> which build to take (or whether to slip if this build fails).
Same opinion here. +1 for RC10, and the we'll take a decision based on tests' results.
--- Additional comment from Dennis Gilmore on 2015-10-29 16:50:43 EDT ---
+1
--- Additional comment from Fedora Update System on 2015-10-29 17:04:55 EDT ---
yelp-3.17.2-3.fc23 has been submitted as an update to Fedora 23. https://bodhi.fedoraproject.org/updates/FEDORA-2015-35a19b33ae
--- Additional comment from awilliam on 2015-10-29 19:34:59 EDT ---
Discussed at 2015-10-29 Go/No-Go meeting, acting as a blocker review meeting: https://meetbot-raw.fedoraproject.org/fedora-meeting-2/2015-10-29/f23-final-go_no_go-meeting_2.2015-10-29-16.00.html .
NOTE: this meeting occurred BEFORE #c9.
At the meeting this bug was rejected as a blocker, on the basis that there are no release criteria it violates, and accepted as a freeze exception issue for the significant impact both in terms of people not having access to Help during installation, and just how bad it looks. As discussed above, since the meeting, a plan was evolved to build an RC10 which should fix this bug, and decide at the next Go/No-Go meeting tomorrow (2015-10-11) whether to ship RC9 or RC10 (or do something else).
--- Additional comment from awilliam on 2015-10-29 20:46:27 EDT ---
The anaconda fix is confirmed in RC10 Workstation live, I'll check KDE as well. Help for GNOME apps still works too.
--- Additional comment from awilliam on 2015-10-29 21:18:39 EDT ---
Yep, good in KDE too.
--- Additional comment from Fedora Update System on 2015-10-31 12:04:47 EDT ---
yelp-3.17.2-3.fc23 has been pushed to the Fedora 23 stable repository. If problems still persist, please make note of it in this bug report.
argh, cloning bugs is considered harmful. you now have a bunch of unnecessary text in the first comment, a bunch of CCs, blocker metadata, and an upstream bug reference, none of which are actually relevant to this bug. And the bug summary is not correct.
I wish we could just remove the damn Clone button from the interface entirely.