Red Hat Bugzilla – Bug 902500
Publican-based books in GNOME Shell
Last modified: 2013-04-18 08:01:49 EDT
I am opening this bug to track ideas of how to improve the way we present Publican-based books in GNOME Shell.
Currently, publican package creates an RPM that installs html-desktop files in /usr/share/doc/<guide><BCP47_locale_tag><...>/
It also installs a .desktop file which uses the Documentation category.
We use the default browser to view the Publican-based books. The browser doesn't allow us to easily assemble a list of locally installed documentation that we could present to users.
Installing a .desktop file also seems to conflict with the Fedora / GNOME design goals and the primary way users are supposed to access documentation in GNOME Shell (via yelp).
See the related feature page:
A related bug filed against the Fedora Release Notes:
Possible solution would be to use yelp to access both the GNOME and Fedora documentation.
See also the following links to a related discussion from 2009:
To assemble a list of locally installed documentation, yelp upstream maintainer indicates that the current installation path used in Publican RPMs needs to change to a system that makes assembling the list possible, eg. to the system used for GNOME documentation:
Note: With the above system, we can also use GNOME's help: uri scheme to access the documentation installed in /usr/share/help/.
For more background information, see:
The main difference between the Publican and GNOME system is that Publican uses the BCP47 locale tags and does not use subdirectories for locales while GNOME documentation uses gettext-based locale tags as subdirectories of /usr/share/help/.
As indicated above, GNOME's system:
* allows to point to a translated document based on the current system locale (with a uri scheme, from within a .desktop menu category etc.),
* makes it easier to assemble a list of installed documentation and implement a search provider to allow users to search for documentation and its content in GNOME Shell.  
 See the related GNOME feature page: https://live.gnome.org/ThreePointSeven/Features/IntegratedApplicationSearch
 Similarly to other GNOME Shell search providers, we could support indexing documentation packages, see: https://bugzilla.gnome.org/show_bug.cgi?id=690058
CC'ing publican-list and docs to get community feedback.
The .desktop file is needed for other desktop environments, IIRC. I'm pretty sure they are mandatory in the Fedora packaging guidelines. Now that I think about it, I'm not sure why they wouldn't be needed in GNOME.
I also seem to remember that we have to tweak the .desktop file that Publican provides when we publish the Fedora Release Notes but I'd let someone else speak to that.
Hi, it's highly unlikely this will get addressed by the Publican team. We'd be happy to take patches though.
Note that you can use publican to build the HTML etc without using its packaging mechanism, so there is nothing stopping anyone with a minimal understanding of spec files from doing whatever they like with the output.
e.g. pop something like this in to a specfile
publican build --langs all --formats html --publish
rm -rf $RPM_BUILD_ROOT
mkdir -p $RPM_BUILD_ROOT/usr/share/help/
for lang in 'en-US' 'de-DE'; do
olang=`sed -e 's/-/_/g';
install publish/$lang/Publican/3.1/html/Users_Guide $RPM_BUILD_ROOT/usr/share/help/$olang/Publican;
Untested, but you get the idea, if you aren't happy with the way it packages things just use publican like any other command line tool and forget it does some automated packaging.
A few highlights:
- Localized files are in subdirectories
- Desktop file is localized at build time. The actual action line cannot be localized, ie Exec or URI, but we can localize name and comment.
I'm intrigued by the idea of documentation as a search provider.
*** This bug has been marked as a duplicate of bug 785751 ***