*** Bug 72137 has been marked as a duplicate of this bug. ***

This breaks every single app, AFAICT, so marking up; perhaps the wipro
people will be able to look at it. Kevin: if all of this is fixed,
will the apps trying to call help be automagically fixed or will work
also be needed on their end? I'm getting conflicting reports on this,
and I don't know the API at all, and (if that is the correct thing to
do) I'd like to mark the large number of 'help doesn't work' bugs as a
duplicate of this.

I have fixed gnome_help_display yesterday.

Luis there's two issues with regards to applications and help. This
bug is really about the help menu items showing up automatically for
apps. If this bug is fixed then all the apps with help will get the
menu items (well all the apps adding a GNOMEUIINFO_HELP item to their
menu structure).


The second issue is help buttons and dialogs, and applet right click
menus. There, applications need to explicitely call gnome_help_display
so there needs to be a bug filed for each individual app.

Kevin: OK, thanks for clarifying that. Is the general all-purpose
stuff fixed, then? i.e., if an app calls gnome_help_display correctly
it will actually work? If so, should we close this general bug and go
about filing the specific bugs?

Adding cc's of the supposedly relevant people. At this point, we're
looking at releasing a completely untested help system that no one
will have time to use or test. That's... well, it sucks a lot. :/

If anyone thinks it would help, I can bring in some wipro people to
help fix/patch things, but I get the impression that the API is still
broken enough that would not be useful.

When I submitted this in a duplicate bug, I said:

"GNOMEUIINFO_HELP() menu items display a submenu based on the stuff in
the installed topic.dat file. As far as I can tell this isn't working
in any GNOME2 apps. For instance, gnome-hello, or gnome-utils/gcalc."

I see no evidence that this has changed in either gnome-hello or
gcalculator, so I don't think that the general bug has been fixed.

*** Bug 75841 has been marked as a duplicate of this bug. ***

*** Bug 75417 has been marked as a duplicate of this bug. ***

What's the situation on this bug?

Satyajit has submitted a patch to the list:

http://mail.gnome.org/archives/desktop-devel-list/2002-March/msg00787.html

I had to disable warnings to get it to build:

cc1: warnings being treated as errors
gnome-app-helper.c:1143: warning: `get_topics' defined but not used
make[1]: *** [gnome-app-helper.lo] Error 1
make[1]: Leaving directory
`/home/jfleck/gnome/head/cvs/libgnomeui/libgnomeui'
make: *** [all-recursive] Error 1

With that done, it works, kinda. It still gives an obscenely long menu
of help items that we don't need, but I click on them and up pops Yelp
with the gnome-calculator help file displayed!

That, um... doesn't sound like a good solution to me :/ We shouldn't
settle for a suboptimal solution just because we feeled pressed by a
deadline. That said... if jfleck, satyajit, and I are the only ones
who give two shits.... :/

Nononono. I didn't mean I accept the solution, I just mean it's an
exciting step in the right direction! The bit that displays in the
menu definitely needs to be cleaned up before this'll be acceptable.

Thanks for the comments jfleck . I am just waiting for people 
to discuss it and then we can come up with one standard solution 
for the issue.
Whether it will be "Contents" or "_HelpContents","htmls" or "xmls".
For that I sent the gifs also, to let people see how it looks :).
Hope we can find a optimal solution soon. 

The warnings during compilation will go after a code clean up. 
get_topics() etc functions were earlier used to parse the TOC file.
I haven't removed the function definations yet . 

About "getting  an obscenely long menu of help items",
I only see "About" (application specfic) and "_Help Contents" 
in help menu. John can you let me know what exactly you are getting.
It will help me resolving the issue  and also find out why it is so
at your end.
 

Now I only get "about" and no help links at all. :-(
I didn't recompile anything - the help items just stopped showing up.

Rebuilt libgnomeui and gcalc again, now I only get "about" and "Help
contents" in the help menu, which is fine.

Made some changes to the diff (as per Havoc's comments) and added a
check condition (taken from the previous code).Thanks john for
applying and testing the patch. 
 

Created attachment 7500 [details] [review]
earlier patch little modified .

With the latest patch and the earlier gcalc patch, I have no help item
in the gnome-calculator help menu at all.

The latest patch has little modification to the old patch . Should 
not create any problem I think . Are you getting any warning
as " GnomeUIInfo->moreinfo cannot be NULL". Sincerely i can't find out 
what could be causing this.  

i spent some time trying to get bug-buddy's gnome_help_display() to
work.  it's kind of complicated but i made some progress.

will look at it more tomorrow.

Help doesn't work for Panel(version 1.5.15).

after looking into it more today, i am pretty sure the libgnome bits
are working.

i'm attaching a newer revision of the gnome-app-helper patch.

i think it's right, but i can't get scrollkeeper/yelp to work.  i was
going to try scrollkeeper 0.3.6, but that needs some different xml
stylesheet things, which wants a newer jade...

from reading gnome-docu/gdp/gnome2_help_api it does look like this
should work as long as scrollkeeper/yelp are working right.

Created attachment 7536 [details] [review]
new version of satyajit kanungo's patch

With Jacob's patch to libgnomeui, Satyajit's gnome-calculator patch,
and a working ScrollKeeper/Yelp setup, this now works.

jfleck verified that with a working yelp/scrollkeeper the patch works.

fixed in CVS:

2002-04-04  jacob berkman  <jacob@ximian.com>

	* libgnomeui/gnome-app-helper.c (create_help_entries): just create
	1 entry which shows the table on contents
	(help_view_display_callback): display our help file
	(quote_string):
	(get_toc_location):
	(get_best_toc_location):
	(get_topics): kill unused functions

	fixes #73312, based on patch from Satyajit Kanungo
	<satyajit.kanungo@wipro.com>

Currently applications need to pass GNOME_PARAM_APP_DATADIR in 
program_init() or popt_init() to pass the name of the application,
required for gnome_help_display().

Creating a patch for libgnome so that application/applets
need not pass GNOME_PARAM_APP_DATADIR or set the DATADIR to 
enable help.

Created attachment 7651 [details] [review]
patch for libgnome for gnome_help_display

Reopening, then, until this patch is applied, and retitling a bit.

this patch is wrong for apps installing outside of where gnome was
installed, right?

the correct thing is for apps to pass in their data dirs.

ok.

so what actually is the problem?

afaict:

1) libgnome API works
2) libgnomeui API works
3) if you have working scrollkeeper/yelp, it all works

Correct with the existing patches help is going to work for the
applications. But we need to pass the DATADIR for each application.

The problem comes while enabling help for applets.
The applets are either under gnome-applets or under
gnome-panel/applets .

Now applets under gnome-applets/ call PANEL_APPLET_BOBONO_FACTORY
macro for the initialization . And to enable help on them we need to 
modify this macro (under gnome-panel/libpanel-applets) to pass
GNOME_PARAM_APP_DATADIR .

For applets present under gnome-panel/applets there is no
initialization for individual applets and intialization is there only 
for gnome-panel. 

The above patch for libgnome, only elliminates the constraint for 
passing DATADIR and GNOME_PARAM_APP_DATADIR for each application 
or applets for enabling help. 
   
I got the problem that can be caused by the above patch (for
applications installed outside gnome). But I still think we got to
modify gnome_help_display (under libgnome) to enable help for
applets.  

 

afaict, PANEL_APPLET_BONOBO_FACTORY *does* set GNOME_PROGRAM_APP_DATADIR.

from gnome-program.h:

#define GNOME_PROGRAM_STANDARD_PROPERTIES \
        GNOME_PARAM_APP_PREFIX, PREFIX,         \
        GNOME_PARAM_APP_SYSCONFDIR, SYSCONFDIR, \
        GNOME_PARAM_APP_DATADIR, DATADIR,       \
        GNOME_PARAM_APP_LIBDIR, LIBDIR


so what else needs to be done here?

or are you talking about shlib applets?  in that case, yes they need
to register a GnomeProgram and pass that to gnome_help_display_desktop().

we could change the shlib applet api to do this.

adding markmc to the cclist...

It doesn't work for the mini-commander applet. I get this error

** (mini_commander_applet:18263): WARNING **: help error: Unable to
find the GNOME_FILE_DOMAIN_APP_HELP domain


It's not clear to me how this should be set. 

if you look at panel-applet.h you will notice:

#if defined(PREFIX) && defined(SYSCONFDIR) && defined(DATADIR) &&
defined(LIBDIR)
#define PANEL_APPLET_BONOBO_FACTORY(iid, type, name, version, callback, data)	\

...

i reccommend doing AC_DEFINE's for PREFIX, SYSCONFDIR, DATADIR, and
LIBDIR in gnome-applets' configure.in so you don't have to add those
to the Makefile.am for each applet.

again, shlib applets need to create their own GnomeProgram and call
gnome_help_show_desktop()

Yeah jacob it works for me. I am putting the patches for applets 
for enabling help on them.
Kevin you can try the mini-commander now with the patch at #80179.
Hope it shall work for you also.
Jacob can  you please verify the patch at #80179. Your comments shall 
help .

ok, so what needs to be done for this bug to be closed?

I am working on shlib applets . If help can be enabled for shlib 
applets also we can close this bug.

I am working on shlib applets . But I find some issue 
with gnome_help_display_desktop().

1. It finds the path using GNOME_PARAM_GNOME_DATADIR 
   will it not create issue if gnome-panel is installed outside 
   the gnome.

2. gnome_help_display_desktop() is not returning the absolute path 
   rather it finds the   relative path and I can't open the help 
   file in the help browser.  (yelp won't work for relative paths)
   I did some changes to the API, to get the absolute path.
    
   Please see the discussion at #79870

   

the entire ghelp:// API is only supposed to work with documents
installed in GNOME_PREFIX/share/gnome/help so I don't think that's an
issue.

I've been thinking that it might be a good idea to be able to open a
document by referring to it's seriesid (which is stored in scrollkeeper).

This 'seriesid' is a string unique to a document. Neither Yelp or
libgnome supports this currently though.

Thoughts about adding this support, that way any document stored in
Scrollkeeper could be displayed no matter where it's stored on disk.

which GnomeProgram are you passing to gnome_help_display_desktop()? 
NULL, or one created by the applet?

it should be getting the datadir from the GnomeProgram, which should
be created by the applet.

is this what you are doing?

Mikael, what is 'GNOME_PREFIX' ?

where scrollkeeper is installed?

where libgnome is installed?

where yelp is installed?

...?

Sorry, I was referring to where libgnome is installed (I assumed that
it used $datadir for libgnome to find the document, does it use
$datadir for the application?)

|the entire ghelp:// API is only supposed to work with documents
|installed in GNOME_PREFIX/share/gnome/help so I don't think that's an
|issue.

So what should third-party applet authors be doing? installing in
there? [Honest question, I don't know the answer to that.]

We really need some kind of resolution on this, FWIW; a stable/frozen
libgnomeui is going to be needed RSN.

hnmmm .: I think I was wrong, it should work for apps installed
outside of libgnome's prefix ( I think ? )

 Jacob as you suggest the shlib applets need to create the 
 GnomeProgram and then call gnome_help_display_desktop().

1. Individual  applets need to do a gnome_program_init() to create 
   the GnomeProgram ?? or they have to use other call 
   (gnome_program_get() ) . For gnome_program_init() it would need
   argc  and argv . Where to get them from ?

2. If we use gnome_help_display_desktop(), it will try to get the 
   help file from  GNOME_PARAM_GNOME_DATADIR, which will have the path 
   where gnome is installed right ?? 
 
 I am bit confused on how the GnomeProgram (created for each applet) 
 will be used in the help API.
  
   

   

in your applet's help callback:

help_cb (...)
{
    static GnomeProgram *applet_program = NULL;

    if (!applet_program) {
        int argc = 1;
        char *argv[2] = { "my-applet" };
        applet_program = gnome_program_init ("My Foo Applet", VERSION,
            LIBGNOME_MODULE,
            argc, argv,
            GNOME_PROGRAM_STANDARD_PROPERTIES,
            NULL);
    }

    gnome_help_display_desktop (applet_program, doc_id,
        file_name, link_id, NULL);
}


i am pretty sure that will work.

(in all honesty i don't personally like the GnomeProgram API but it's
too late to fix that now)

did this clarify things?

 My concern is use of  "gnome_help_display_desktop()"  API.

 It passes  GNOME_FILE_DOMAIN_HELP as the domain . And in 
 gnome_program_locate_file() ( gnome-program.c ) uses  
 GNOME_PARAM_GNOME_DATADIR to get the path.

 Hence the "datadir" will  be the path where gnome is installed. 
 The use of display_desktop()  api won't work if gnome-panel is 
 installed at some other location.

 

well, do we really have to support having the gnome-panel installed in
another location?

Another solution would be to add a function or two to the libgnome
help api which enables you to call with scrollkeeper-path or the
scrollkeeper seriesid.

gnome_help_show_help ("/GNOME/Applications/gedit", "section_id");
gnome_help_show_help_id ("52bf9656-2acc-11d6-82e0-8f1c98991558", 
                         "section_id");

The seriesid is a string unique to every document.

This means for applications that add themselfs in ScrollKeeper (which
they should) they can use this and we don't have to care where it's
installed.

It might be a little late to add this now but it should imho have been
done from the beginning.

i'd say that's a bug in gnome_program_locate_file() then ;)

post a patch changing it to use GNOME_PARAM_APP_DATADIR to
desktop-devel, and see if anyone objects.

Mikael, it's not a matter of the panel being in a different prefix,
but some 3rd party applet.

Well this bug is never going to be closed I think :)

One more issue the way gnome_help_display() and
gnome_help_display_desktop() is going to work will it  be possible to 
access any help document from any location by any application.

For example it's being planned to put the user guide (The help
document for nautilus/panle/control center etc) at one location 
and allow panel/nautilus/control center capplets etc to access it 
from that location. This will help in not duplicating the help 
documents. 

Is bug 79911 a dup of this?

Marking this bug as invalid, as there is already too much crap in it
and the sub-bugs have already been identified:

  - Bugs in gnome-help.c (logged as #82140)
  - Bugs in gnome-app-helper.c (to be determined; I will take
    care of this)
  - Bugs in yelp (already logged)
  - Bugs in shlib applets that do not create their own
    GnomeProgram.  Please file a bug for each shlib applet that
    does not do this correctly.  If you want, assign them to
    myself.
  - Incorrect installations of scrollkeeper and/or the DocBook stuff.
    This is a distribution issue anyways.

Please do ***NOT*** reopen this bug.  Open fine-grained bugs for each
problem you find, but please do not create an ambiguous and
hard-to-read monster bug.

[Luis, #79911 is not a dupe.]