Some GNOME only help showing up in Unity help (13.10)

[Vassili Platonov]

In ubuntu-docs conditionals are used for topics that are unity only or GNOME only or both.

There are an unknown number of cases where help topic information
that should only be for the GNOME desktop are available under the Unity desktop. This is at least partially due to the 13.10 documentation string freeze occurring before the newer upstream GNOME docs could be completely merged with ubuntu-docs.

As a secondary issue, some image files appear to be missing.

The issue includes, but may not be limited to, files.preview.page (and the compiled files-preview.html), a11y-icon.page (and the compiled a11y-icon.html).

The related image files are: view-fullscreen-16.png and view-fullscreen-16.png.

The compile process complains about a third missing image file, display-dual-monitors.webm, but from a different root cause that will (eventually) be covered in another bug report.

It is unlikely that the issues can be fixed before the final doc freeze in a few days. It will have to be either via SRU or in 14.04.

Note: the subject and description for this bug report have been significantly changed, such that the first few additional postings below might seem out of place at first.

[Doug Smythies (dsmythies)]

The file "files-preview.page" is only called from within a NOT unity conditional statement within "files-browse.page". If the desktop is NOT unity (i.e. GNOME) then the ubuntu-help docs are not used, but rather the GNOME help docs are used. I am saying that are not any conditions where the system would be looking for the file "view-fullscreen-16.png" and therefore it has purposely not been included. I'll look into deleting "files-preview.page", but the build might complain without it.

Note also for local help using yelp, as opposed to observing the built HTML, an up to date 13.10 computer should be used, as it contains some fixes to yelp as to what is displayed.

The referenced video is purposely not included for the same reason, it is within a never accessible conditional statement.

Due to a yelp-build issue, when compiling the code, these files show as missing.

[Doug Smythies (dsmythies)]

In the compiled html, there are two links to files-preview.html, one from file.html and one from nautilus-preview.html.

[Vassili Platonov (vassilip)]

Thanks for the detailed answer.
I think that is because my hands had some curves when I'll tried to compile ubuntu-help ((

BTW, would you be so kind to tell me about compilling ubuntu-help translation with flag 'platform:unity'? It seems that instructions at https://wiki.ubuntu.com/DocumentationTeam/Translation are out of date.

[Doug Smythies (dsmythies)]

The platform specification was added to html/ubuntu.xsl in revision 233.

http://bazaar.launchpad.net/~ubuntu-core-doc/ubuntu-docs/saucy/revision/233

You shouldn't have to worry about it. I only use this reference to build all languages:

https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/BuildingDocumentation

We know that many of the wiki pages are not up to date and we are trying to fix them, but progress is very slow.

As for this bug report: I have tried both unity and GNOME desktops on one of my 13.10 virtual computers, and neither behaves as described by the files-preview.html page. I also haven't yet figured out how the links to that page got into file.html and nautilus-preview.html.

[Vassili Platonov (vassilip)]

Thanks again for useful references.

As for this link's behavior: I'm just a translator and, unfortunately, can't help. Sorry.

But I found some strings that are not marked '!platform:unity' or something else, where gnome terms are present (i.e. top bar instead Launcher, Activities instead Dash, etc). Is it worth to collect them somewhere, for example in this bug report, or it better to fill a new report?

[Doug Smythies (dsmythies)]

I'm not sure, maybe someone else knows better. I am actually not very experienced at using either unity or GNOME desktops, and do not know the terminology well. (I actually normally use ubuntu server).

[Doug Smythies (dsmythies)]

The html build seems to include files-preview links via the xref="files" line, and ylep-build doesn't seem to realize that it is an unmet conditional. Similarly for the nautilus path. Since I normally compile on a 12.04 server, I also did a check compile on my 13.10 VM desktop, which would be sure to use the latest tools.

References:
files-preview.page:6: <link type="guide" xref="files"/>
files-preview.page:7: <link type="seealso" xref="nautilus-preview"/>

I didn't comment on universal-access-menu.png yet. It seems to be the same thing, where a11y-icon.page is called conditionally, or even nested conditionally. Again, the html build differs from yelp help with what ends up being displayed.

[Doug Smythies (dsmythies)]

Actually, the installed yelp help has the same issues as the built html. (I was using the wrong version of help before). This will require a string freeze exception to fix.

[Vassili Platonov (vassilip)]

I think that this examination will help to solve a problem:

The <if:choose> element doesn't provide fallback content in some cases. Look at the page https://help.ubuntu.com/13.10/ubuntu-help/color.html and compare it with https://help.gnome.org/users/gnome-help/stable/color.html . Under the title "How do I assign profiles to devices?" there should be a description for platform:unity "Look in System Settings->Color for the option to change this." or fallback description "Look in Settings->Color for the option to change this." But description doesn't display even as fallback content.

Code for this page is located at C/color-assignprofiles.page. The specification of projectmallard.org/if/1.0 allows two different ways to provide fallback content for <if:choose> elements. Instead of using an <if:else> element, you can put fallback block content directly in the <if:choose> element. Supporting tools will treat this exactly as if you had used an <if:else> element, but non-supporting tools will show this fallback content.

But this doesn't occur. The <if:choose> element is located in the <info> element. I tried to use it in the <desc> element but then description displays both content at the same time. It seems that conditionals (eg. <if:choose>) can not be used in information elements such as <info> or <desc> as they are not general block elements.

Is there a restrictions or even a bug in Mallard? If so, this will narrow our search for solution.

[Doug Smythies (dsmythies)]

New upstream yelp-tools fix these issues, I think. They have yet to propagate down to Ubuntu, but we hope they will be 14.04 release. There a couple of other issues with this stuff, where even the GNOME docs do not reflect the GNOME DeskTop. Somehow we'll sort it all out.

[Doug Smythies (dsmythies)]

This was not only a yelp-tools issue. It was also a code issue.