Bug 1276226

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.

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.

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.

'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.

I've also seen this on the 32bit workstation.

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.

(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?

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.

Could we get anaconda to install its help files properly, and use 

yelp help:anaconda

?

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.

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.

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.

(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.

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.

Created attachment 1087651 [details]
Top-level DocBook file to include all sections

oh, that actually works. Thanks, Shaun

we'd still need to teach anaconda to open the section names, though. I don't know how hard that is.

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.

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.

(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.

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.

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.

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).

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.

I am +1 to this plan.

+1 to spin a rc10 for just this FE and we decide tomorrow which to go with.

(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.

+1

yelp-3.17.2-3.fc23 has been submitted as an update to Fedora 23. https://bodhi.fedoraproject.org/updates/FEDORA-2015-35a19b33ae

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).

The anaconda fix is confirmed in RC10 Workstation live, I'll check KDE as well. Help for GNOME apps still works too.

Yep, good in KDE too.

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.