Helpfiles for plugins?

[blog.brockha.us]

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?

[garvinhicking]

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

[blog.brockha.us]

This is exactly, what I intended.

[garvinhicking]

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

[blog.brockha.us]

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.

[garvinhicking]

Hi!

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.

I'd be interested in your approach, so please have a go.

If you won't find the time in the coming weeks, I can try to kick in.

Best regards,
Garvin

[blog.brockha.us]

Okay, that's how we'll do it.

[blog.brockha.us]

Well, I noticed you worked on this topic. I found an entry in the NEWS file of s9y:

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)

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.

[garvinhicking]

Hi!

Fixed!

Regards,
Garvin

[blog.brockha.us]

Thanks, Garvin, for quick reaction..

[blog.brockha.us]

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?

[garvinhicking]

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

[blog.brockha.us]

Thanks, Garvin, that fixes my problem!