Hi folks,
I want to discuss shortly the expected behavior of plugin_help()-function implemented by plugins. Inside API-documentation its written:
Called whenever the plugin should show its documentation (if any).
This may open a dialog, a browser with a website or a local installed HTML help file(see utils_start_browser()) or something else. Can be omitted when not needed.
Well... which means its not really defined what the user will expect once he push the button. Therefore we do have at least 2.5 major behaviors: - Geany is calling a browser and opening a webpage with info (spellcheck plugin) - Its opening a message window with * a short info about plugin (e.g. geanyLaTeX) * a long help text about plugin (e.g. geanymacro) Question is, what do we really want to have behind that function?
Cheers, Frank
Hi Frank,
Good question.
Well... which means its not really defined what the user will expect once he push the button. Therefore we do have at least 2.5 major behaviors:
- Geany is calling a browser and opening a webpage with info (spellcheck
plugin)
Which gets a 404 error for me, and anyway expecting online connection for a local plugin is *very* rude. If you provide a webpage make it local. And if it is online make sure it is available!
- Its opening a message window with
* a short info about plugin (e.g. geanyLaTeX) * a long help text about plugin (e.g. geanymacro)
Neither of these provide much "help", if its called help then provide *user* help, not something useless. </rant>
Question is, what do we really want to have behind that function?
The delivery format is less important than actually providing help.
That said, a webpage provides some formatting that helps to structure the information, but it does need to meet the "good webpage guide" as defined by me ;-) (can be resized, uses my default text size, not more than 40em wide text lines, *nothing* is pixel based, works in all major browsers)
Cheers Lex
Am 07.03.2012 09:26, schrieb Lex Trotman:
Hi Frank,
Good question.
Well... which means its not really defined what the user will expect once he push the button. Therefore we do have at least 2.5 major behaviors:
- Geany is calling a browser and opening a webpage with info (spellcheck
plugin)
Which gets a 404 error for me, and anyway expecting online connection for a local plugin is *very* rude. If you provide a webpage make it local. And if it is online make sure it is available!
I agree.
Question is, what do we really want to have behind that function?
The delivery format is less important than actually providing help.
I guess that's set. But how would such a thing look like?
Cheers, Frank
[...]
Question is, what do we really want to have behind that function?
The delivery format is less important than actually providing help.
I guess that's set. But how would such a thing look like?
Well, since you are trying to get GP plugins to provide a ReST formatted readme why not make it a recommendation for a ReST formatted help which the GP build script can turn into an installed html file. So the plugin_help() just needs to call utils_open_browser().
Use the same css as Geany's manual and get a consistent look and feel.
As to content, first guess recommended layout:
How to use -------------- What it does, menu items, keybindings
Preferences --------------- blah
How to configure ---------------------- blah
The last is only needed if there is configuration beyond the preferences settings.
Cheers Lex
Am 12.03.2012 00:24, schrieb Lex Trotman:
[...]
Question is, what do we really want to have behind that function?
The delivery format is less important than actually providing help.
I guess that's set. But how would such a thing look like?
Well, since you are trying to get GP plugins to provide a ReST formatted readme why not make it a recommendation for a ReST formatted help which the GP build script can turn into an installed html file. So the plugin_help() just needs to call utils_open_browser().
Use the same css as Geany's manual and get a consistent look and feel.
As to content, first guess recommended layout:
How to use
What it does, menu items, keybindings
Preferences
blah
How to configure
blah
The last is only needed if there is configuration beyond the preferences settings.
I like that idea.
Cheers, Frank
On Wed, 7 Mar 2012 19:26:45 +1100, Lex wrote:
Hi Frank,
Good question.
Well... which means its not really defined what the user will expect once he push the button. Therefore we do have at least 2.5 major behaviors:
- Geany is calling a browser and opening a webpage with info
(spellcheck plugin)
Which gets a 404 error for me, and anyway expecting online connection
Oops. I'm afraid this is already broken for a very long time but now fixed.
If there is a final solution to the general question about the Help button behaviour, I'm willing to change the Spell Check plugin accordingly.
Regards, Enrico
P.S.: please don't wonder about the late reply+fix, I'm terribly behind the list traffic :(.
Well... which means its not really defined what the user will expectonce he push the button. Therefore we do have at least 2.5 major behaviors:- Geany is calling a browser and opening a webpage with info (spellcheck plugin) - Its opening a message window with * a short info about plugin (e.g. geanyLaTeX) * a long help text about plugin (e.g. geanymacro) Question is, what do we really want to have behind that function?
I think that a full help text is the best (but having written geanymacro you could argue I'm a bit biased). The reason is, that I think that a user should not have to get the source, and look at the readme file to know what a plugin does, or what the options mean. It is much more convenient for the user to have it there when they press the help button for that plugin.
William