Bug 770069

There are several things to update:

a) Support for .document files has been dropped: there was nobody adopting it, so no reason to keep that.

The work-around is to create a symlink:
 $ ln -s /usr/share/doc/manual/opensuse-manuals_en /usr/share/help/C/opensuse-manuals
You can do the same for other languages. You can then access the help with "yelp help:opensuse-manuals"

b) When started with no argument, yelp doesn't display any index anymore, but the general gnome help.

I don't have a good solution for this, except possibly patching gnome-user-doc to link to the openSUSE doc.

For b: simply adding something like:

 "<p>See also the <link href="help:opensuse-manuals">openSUSE manual</link>.</p>"

to /usr/share/help/C/gnome-help/index.page (or the translated version) works fine.

Ok, thanks for the info--I'll try to change the documentation packages accordingly.

(In reply to comment #2)
> For b: simply adding something like:
> 
>  "<p>See also the <link href="help:opensuse-manuals">openSUSE
> manual</link>.</p>"
> 
> to /usr/share/help/C/gnome-help/index.page (or the translated version) works
> fine.

Ok, this works :)  Now I'm not sure whether we are actually allowed to add something to /usr/share/help/C/gnome-help/index.page and if yes, how?  We surely cannot require gnome-help/index.page and thus soemthing in the package's %post would be unreliably.

I'd appreciate if yelp would also find the opensuse docs via this "All Help Documents" interface.  Docs from /usr/share/gnome/help seem to appear there.  Shall we links the opensuse-manuals to that location?  And which (*.page) would be needed?

(In reply to comment #4)
> Ok, this works :)  Now I'm not sure whether we are actually allowed to add
> something to /usr/share/help/C/gnome-help/index.page and if yes, how?

I see no reason why we wouldn't be allowed to patch the gnome-help document. It's really just a patch to do in the gnome-user-docs package.

> We surely cannot require gnome-help/index.page and thus soemthing in the
> package's %post would be unreliably.

I'm not sure what you mean here. We actually need the package providing gnome-help/index.page (gnome-user-docs) if yelp is installed since that's the default help that is shown when you start yelp.

> I'd appreciate if yelp would also find the opensuse docs via this "All Help
> Documents" interface.  Docs from /usr/share/gnome/help seem to appear there. 
> Shall we links the opensuse-manuals to that location?  And which (*.page) would
> be needed?

This should work if you do the symlinks I suggested in comment #1. (reading the code) Ok, it only works for mallard docbook documents, since those have a file from which a title can be deduced. I guess we could make it work by patching the code to look for some specific files somewhere, that would document what the manual is about (a bit like the .document files).

(In reply to comment #5)

> I see no reason why we wouldn't be allowed to patch the gnome-help document.
> It's really just a patch to do in the gnome-user-docs package.

Ok, but wouldn't this mean that g-u-d would have to require opensuse-manuals_en (and the translations)?

> > We surely cannot require gnome-help/index.page and thus something in the
> > package's %post would be unreliably.
> 
> I'm not sure what you mean here. We actually need the package providing
> gnome-help/index.page (gnome-user-docs) if yelp is installed since that's the
> default help that is shown when you start yelp.

At first, I thought about patching at installation time (I guess that only allowed if we consider index.page as a configuration file).  It is probably better to patch at packaging time.

> This should work if you do the symlinks I suggested in comment #1. (reading the
> code) Ok, it only works for mallard docbook documents, since those have a file
> from which a title can be deduced. I guess we could make it work by patching
> the code to look for some specific files somewhere, that would document what
> the manual is about (a bit like the .document files).

If it is easier we could also add a .page (mallard) file to the opensuse-manuals_en package assuming that you somehow can reference html from a mallard .page file.  Which seems to be possible because we already did this from gnome-help/index.page --I'll give this a try on Monday (maybe, I'll also post to the gnome-docs ML asking for advice :) ).

Thanks for all your help thus far!

I figured out that it works without patching any index.page :-)

We just must generate a project specific page with a "guide" link back to the main index page.  I'll attach an example.  toms, can you please write a style sheet that collects all the needed info and builds such a page?  I marked the dynamic contents with <!-- ^^^^^^^^^ -->; this will be project specific (openSUSE, SLES, SLED, SLEPOS, etc.).

I'll also attach how my manually edited draft file appear rendered in yelp.

Created attachment 497922 [details]
yelp index.page with "openSUSE Documents" at the end

Created attachment 497924 [details]
opensuse.page rendered in yelp

Created attachment 497925 [details]
example of opensuse.page

To be installed in /usr/share/help/C/gnome-help.

Ok, see revision#1709 in our SVN or use daps/daps-xslt/page/docbook.xsl for the current implementation. Please test.

Note: If an article or book does NOT contain an @id, it won't be included into the output format. In such a case, the stylesheet prints a warning.

Setting it to resolved. Feel free to reopen it, if necessary.

Thanks, this looks pretty good!  I now have feedback how you can reference HTML sub-pages directly.  It would be nice if you could enhance the page accordingly, e.g.:

    help:opensuse-manuals/book.opensuse.startup
           ^^^^^^^^^^^^      ^^^^^^^^^^^^^^^
         package name w/o    ID of the subdocument
         language code;      (= file name without
         configurable via     the .html suffix)
         a style sheet
         parameter

TIA!

(In reply to comment #12)
> Thanks, this looks pretty good!  I now have feedback how you can reference HTML
> sub-pages directly.  It would be nice if you could enhance the page
> accordingly, e.g.:

Thanks for the info. I've implemented this linking scheme into the stylesheet. 
Ready to test. :)

Thanks, together with the (now implemented) additional enhancement requests, it is now done.

Frank, please add daps/daps-xslt/page/docbook.xsl to the daps package.  

For so-called document files (html), we have this:

daps -d DC-opensuse-html document-files-html
daps -d DC-opensuse-html document-files-dir-name

Probably, something similar for this "page" file would be nice.  It usually needs a parameter ("packagename") that I'd provide at package build time manually (~= name of the DEF file without "DEF-").

I think we do not need this for PDF, just HTML would be fine.  Other opinions?

For the moment, I add page/docbook.xsl to the packages.

From what I see, this is fixed (or at least not a bug in yelp).

@Karl: do you agree of either closing the bug (fixed) or move it to Documentation?

Yes, it is now a documentation bug (daps enhancement req).

. ./DC-opensuse-html
xsltproc -xinclude --stringparam packagename opensuse-html %{S:999} \
  $profiled_dir/$MAIN > %{name}.page

Added the respective option to the DAPS devel branch. It will be available with DAPS 2.0.

daps -d <DC-FILE> package-html --pagefiles --name <NAME>

Re-assigning to ke

Thanks, my packaging script now makes use of this new option.