Bug 902500

Summary: Publican-based books in GNOME Shell
Product: [Community] Publican Reporter: Petr Kovar <pkovar>
Component: publicanAssignee: Ruediger Landmann <rlandman>
Status: CLOSED DUPLICATE QA Contact: tools-bugs <tools-bugs>
Severity: unspecified Docs Contact:
Priority: unspecified    
Version: futureCC: jfearn, me, pkovar, publican-list, rglasz, rlandman+disabled, rlandman, sparks
Target Milestone: ---   
Target Release: ---   
Hardware: All   
OS: Linux   
Whiteboard:
Fixed In Version: Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2013-04-18 04:02:19 UTC Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:
Embargoed:

Description Petr Kovar 2013-01-21 19:29:01 UTC
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:

https://fedoraproject.org/wiki/Design/F18_Launcher_Purge

A related bug filed against the Fedora Release Notes:

https://bugzilla.redhat.com/show_bug.cgi?id=846316

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:

https://fedoraproject.org/wiki/Desktop_Documentation_Presentation_Options

https://www.redhat.com/archives/fedora-docs-list/2009-December/msg00031.html

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:

/usr/share/help/<locale>/<package>

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: 

https://live.gnome.org/Design/Apps/Help

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. [1] [2]

[1] See the related GNOME feature page: https://live.gnome.org/ThreePointSeven/Features/IntegratedApplicationSearch

[2] Similarly to other GNOME Shell search providers, we could support indexing documentation packages, see: https://bugzilla.gnome.org/show_bug.cgi?id=690058

Comment 1 Petr Kovar 2013-01-25 15:19:01 UTC
CC'ing publican-list and docs to get community feedback.

Comment 2 Eric Christensen 2013-01-25 15:50:35 UTC
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.

Comment 3 Jeff Fearn 🐞 2013-03-08 05:31:15 UTC
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

%build
publican build --langs all --formats html --publish

%install
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;
done

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.

Comment 4 Pete Travis 2013-03-08 06:29:34 UTC
I have a spec file that does almost exactly that, and the Release Notes have been using a javascript snippet for a while that redirect the user the the appropriate documents. I'm writing something up on the process of using such a spec file to package our docs now, and can post a link in this ticket for the curious.

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.

Comment 5 Jeff Fearn 🐞 2013-04-18 04:02:19 UTC

*** This bug has been marked as a duplicate of bug 785751 ***