Helpfiles for plugins?
-
- Regular
- Posts: 695
- Joined: Tue Jul 03, 2007 3:34 am
- Location: Berlin, Germany
- Contact:
Helpfiles for plugins?
Hello.
As it always is an issue with s9y's documentation is missing, I thought about how to give more documentation on installed plugins to the enduser at least.
The configuration already supports descriptions for the options, but I think, this is a little too -hmm- clumsy. I always seen this as some kind of short descriptions, but as an user I always wanted to see more.
Why not adding a functionality to the serendipity plugin fetching HTML help files in the same way, we find language files? So if i.e. a help.en.html is found the plugin adds a help button, opening this file in a new window. For the options itself we could call html anchors inside of the file (help.en.html#optionname). As this functionality is implemented in the plugin core code, this would be even backward compatible.
I've seen a call for papers describing plugins, why not letting the plugin coders describe plugins on their own with this? The only bad thing coming into my mind is, that these html files could contain anything. But I think, there are no untrusted coders having access to the Spartacus repository, so this shouldn't be too bad.
(Hmm.. Verifying plugins with a s9y trustkey would be a nice feature, too.. Giving a warning for plugins not coming from trusted locations or something.. Just brainstorming.. )
What do you think about this?
As it always is an issue with s9y's documentation is missing, I thought about how to give more documentation on installed plugins to the enduser at least.
The configuration already supports descriptions for the options, but I think, this is a little too -hmm- clumsy. I always seen this as some kind of short descriptions, but as an user I always wanted to see more.
Why not adding a functionality to the serendipity plugin fetching HTML help files in the same way, we find language files? So if i.e. a help.en.html is found the plugin adds a help button, opening this file in a new window. For the options itself we could call html anchors inside of the file (help.en.html#optionname). As this functionality is implemented in the plugin core code, this would be even backward compatible.
I've seen a call for papers describing plugins, why not letting the plugin coders describe plugins on their own with this? The only bad thing coming into my mind is, that these html files could contain anything. But I think, there are no untrusted coders having access to the Spartacus repository, so this shouldn't be too bad.
(Hmm.. Verifying plugins with a s9y trustkey would be a nice feature, too.. Giving a warning for plugins not coming from trusted locations or something.. Just brainstorming.. )
What do you think about this?
-
- Core Developer
- Posts: 30022
- Joined: Tue Sep 16, 2003 9:45 pm
- Location: Cologne, Germany
- Contact:
Re: Helpfiles for plugins?
Hi!
I agree, adding documentation would always be nice. How about a link "Help" inside the plugin configration overview? The place where you can drag+drop links. We could add a simple question mark icon for it, so it wouldn't take up too much place.
The core would look inside a plugin directory if a file "documentation.html" exists. If it does, an empty s9y backend page is called which will include the documentation.html file on a page. We cannot link directly to documentation.html, because the HTTP Path to the plugin's directory cannot always be properly guessed (because plugin directories can be nested in directory - a path like /plugins/my_plugin_checkouts/cvs/serendipity_event_gravatar would be valid, and you can'T easily deduce the HTML path to that, because when you have a symbolic link on my_plugin_checkouts you wouldn't get the HTTP but the filesystem path.
Anyways, then the documentation.html of a plugin would be shown. That html file could have subsections etc, and it could have a very easy, basic layout. It should really be maintained in CVS, because embedding foreign web pages is really too much a security issue.
Best regards,
Garvin
I agree, adding documentation would always be nice. How about a link "Help" inside the plugin configration overview? The place where you can drag+drop links. We could add a simple question mark icon for it, so it wouldn't take up too much place.
The core would look inside a plugin directory if a file "documentation.html" exists. If it does, an empty s9y backend page is called which will include the documentation.html file on a page. We cannot link directly to documentation.html, because the HTTP Path to the plugin's directory cannot always be properly guessed (because plugin directories can be nested in directory - a path like /plugins/my_plugin_checkouts/cvs/serendipity_event_gravatar would be valid, and you can'T easily deduce the HTML path to that, because when you have a symbolic link on my_plugin_checkouts you wouldn't get the HTTP but the filesystem path.
Anyways, then the documentation.html of a plugin would be shown. That html file could have subsections etc, and it could have a very easy, basic layout. It should really be maintained in CVS, because embedding foreign web pages is really too much a security issue.
Best regards,
Garvin
# Garvin Hicking (s9y Developer)
# Did I help you? Consider making me happy: http://wishes.garv.in/
# or use my PayPal account "paypal {at} supergarv (dot) de"
# My "other" hobby: http://flickr.garv.in/
# Did I help you? Consider making me happy: http://wishes.garv.in/
# or use my PayPal account "paypal {at} supergarv (dot) de"
# My "other" hobby: http://flickr.garv.in/
-
- Regular
- Posts: 695
- Joined: Tue Jul 03, 2007 3:34 am
- Location: Berlin, Germany
- Contact:
-
- Core Developer
- Posts: 30022
- Joined: Tue Sep 16, 2003 9:45 pm
- Location: Cologne, Germany
- Contact:
Hi!
Great.
I thought about that we need to have a documentation_XX.html file, where XX represents the language name. So that people can contribute different languages for the docs. It should fall back to 'en.html' if the file does not exist in the user's language.
Would you like to try implementing the core functionality for it, or should I?
Regard,s
Garvin
Great.
I thought about that we need to have a documentation_XX.html file, where XX represents the language name. So that people can contribute different languages for the docs. It should fall back to 'en.html' if the file does not exist in the user's language.
Would you like to try implementing the core functionality for it, or should I?
Regard,s
Garvin
# Garvin Hicking (s9y Developer)
# Did I help you? Consider making me happy: http://wishes.garv.in/
# or use my PayPal account "paypal {at} supergarv (dot) de"
# My "other" hobby: http://flickr.garv.in/
# Did I help you? Consider making me happy: http://wishes.garv.in/
# or use my PayPal account "paypal {at} supergarv (dot) de"
# My "other" hobby: http://flickr.garv.in/
-
- Regular
- Posts: 695
- Joined: Tue Jul 03, 2007 3:34 am
- Location: Berlin, Germany
- Contact:
Hi Garvin.
This again I tried to say in my first post, too.
Well.. Who implements this? I can try, of course. I'm interested in giving you as much time as I can for finishing your "other" s9y project.
But my time gets sparer now, as my normal professional project work is starting again, what is always very time consuming. So I can't implement it immediate, but hey, V..1.2 isn't out yet, so I think there is no hurry for 1.3.
This again I tried to say in my first post, too.
Well.. Who implements this? I can try, of course. I'm interested in giving you as much time as I can for finishing your "other" s9y project.
But my time gets sparer now, as my normal professional project work is starting again, what is always very time consuming. So I can't implement it immediate, but hey, V..1.2 isn't out yet, so I think there is no hurry for 1.3.
-
- Core Developer
- Posts: 30022
- Joined: Tue Sep 16, 2003 9:45 pm
- Location: Cologne, Germany
- Contact:
Hi!
If you won't find the time in the coming weeks, I can try to kick in.
Best regards,
Garvin
I'd be interested in your approach, so please have a go.Well.. Who implements this? I can try, of course. I'm interested in giving you as much time as I can for finishing your "other" s9y project.
If you won't find the time in the coming weeks, I can try to kick in.
Best regards,
Garvin
# Garvin Hicking (s9y Developer)
# Did I help you? Consider making me happy: http://wishes.garv.in/
# or use my PayPal account "paypal {at} supergarv (dot) de"
# My "other" hobby: http://flickr.garv.in/
# Did I help you? Consider making me happy: http://wishes.garv.in/
# or use my PayPal account "paypal {at} supergarv (dot) de"
# My "other" hobby: http://flickr.garv.in/
-
- Regular
- Posts: 695
- Joined: Tue Jul 03, 2007 3:34 am
- Location: Berlin, Germany
- Contact:
-
- Regular
- Posts: 695
- Joined: Tue Jul 03, 2007 3:34 am
- Location: Berlin, Germany
- Contact:
Re: Helpfiles for plugins?
Well, I noticed you worked on this topic. I found an entry in the NEWS file of s9y:
Very cool! Thanks garvin! But it is working only *nearly* at the moment.
The link to the local doc and ChangeLog file is wrong. In the staticpage plugin configuration the links are
http://blog.brockha.us/plugins//ChangeLog
http://blog.brockha.us/plugins//documentation_en.html
in my case. The plugin subdir is missing.
But exept of this: Good work, garvin, thanks a lot! I will implement some documentation on some of my plugins now soon.
Code: Select all
* Added full plugin name and links to documentation/changelog for
plugins on installation and configuration [1.4-beta2]:
You can provide Documentation for your plugins by supplying a local file
called documentation_XX.html inside the plugin directory, which Serendipity
will automatically detect.
You can also (additionally) add a property bag attribute "website" inside
your plugin's introspect() method:
$propbag->add('website', 'http://anypage.com/');
To provide a version history, you can add a file "ChangeLog" (mind the exact
spelling) to your plugin directory.
All three possible links are shown on the Serendipity interface when
configuring or installing a plugin.
(garvinhicking)
The link to the local doc and ChangeLog file is wrong. In the staticpage plugin configuration the links are
http://blog.brockha.us/plugins//ChangeLog
http://blog.brockha.us/plugins//documentation_en.html
in my case. The plugin subdir is missing.
But exept of this: Good work, garvin, thanks a lot! I will implement some documentation on some of my plugins now soon.
-
- Core Developer
- Posts: 30022
- Joined: Tue Sep 16, 2003 9:45 pm
- Location: Cologne, Germany
- Contact:
Re: Helpfiles for plugins?
Hi!
Fixed!
Regards,
Garvin
Fixed!
Regards,
Garvin
# Garvin Hicking (s9y Developer)
# Did I help you? Consider making me happy: http://wishes.garv.in/
# or use my PayPal account "paypal {at} supergarv (dot) de"
# My "other" hobby: http://flickr.garv.in/
# Did I help you? Consider making me happy: http://wishes.garv.in/
# or use my PayPal account "paypal {at} supergarv (dot) de"
# My "other" hobby: http://flickr.garv.in/
-
- Regular
- Posts: 695
- Joined: Tue Jul 03, 2007 3:34 am
- Location: Berlin, Germany
- Contact:
Re: Helpfiles for plugins?
Thanks, Garvin, for quick reaction..
-
- Regular
- Posts: 695
- Joined: Tue Jul 03, 2007 3:34 am
- Location: Berlin, Germany
- Contact:
Re: Helpfiles for plugins?
Next problem: Since I use "Apache mod_rewrite" in the configuration of s9y the links to the documentation of plugins doesn't work anymore.
The link is now
http://blog.brockha.us/plugins/serendip ... on_de.html
but it still should be
http://blog.brockha.us/index.php?/plugi ... on_de.html
The problem might be, that the plugin permalink is not a "rewritten" one. Any ideas?
The link is now
http://blog.brockha.us/plugins/serendip ... on_de.html
but it still should be
http://blog.brockha.us/index.php?/plugi ... on_de.html
The problem might be, that the plugin permalink is not a "rewritten" one. Any ideas?
-
- Core Developer
- Posts: 30022
- Joined: Tue Sep 16, 2003 9:45 pm
- Location: Cologne, Germany
- Contact:
Re: Helpfiles for plugins?
Hi!
Plugins that bundle .html files should deliver a ".htaccess" file with "RewriteEngine Off" to prevent this.
Everything with .html is rewritten by s9y by default to point to the main blog...
Regards,
Garvin
Plugins that bundle .html files should deliver a ".htaccess" file with "RewriteEngine Off" to prevent this.
Everything with .html is rewritten by s9y by default to point to the main blog...
Regards,
Garvin
# Garvin Hicking (s9y Developer)
# Did I help you? Consider making me happy: http://wishes.garv.in/
# or use my PayPal account "paypal {at} supergarv (dot) de"
# My "other" hobby: http://flickr.garv.in/
# Did I help you? Consider making me happy: http://wishes.garv.in/
# or use my PayPal account "paypal {at} supergarv (dot) de"
# My "other" hobby: http://flickr.garv.in/
-
- Regular
- Posts: 695
- Joined: Tue Jul 03, 2007 3:34 am
- Location: Berlin, Germany
- Contact:
Re: Helpfiles for plugins?
Thanks, Garvin, that fixes my problem!