Support Forum

Manfre · Tweet

The help documentation is the biggest hurdle I face when creating plugins. All of my plugins have different layouts and styling with regards to the help documentation and it has always irked me.

It would be a good thing if there existed a template that all plugin developers could follow. This would make the process easier, more consistent and the end result would be much better for the community. It would also allow for the creation of plugin help generators and Textpattern Resources”:http://textpattern.org could host the plugin files and display the help documentation (consistently for all plugins).

The formatting should work without the class specific styles so it can gracefully degrade when only working with an unmodified textpattern.css.

The Sections of a plugin’s help documentation:

ToC (Optional)
Summary
Author Contact
License
Plugin dependencies
Installation steps
Uninstallation steps
Tags (attribute descriptions and examples)
Exposed functions (for class plugins)
Global Variables
Plugin Events
Admin page help
Examples (a large example that puts it all together)

The ToC and a tag index can be auto-generated when the plugin is encoded.

Textile Format:
h1(title). Plugin Title

h2(section). Section Name

p. Section text uses regular paragraph formatting

Section: Tags

All references to a plugin should use the class "tag". E.g. You must include %(tag)mem_awesome_plugin% on every page that...
Each plugin tag would have the following:

h3(tag). prefix_tag_name
p(tag-summary). Description of the plugin tag and how it is intended to be used.
*(atts) %(atts-name)attribute_name% %(atts-type)value_type% Description of the attribute usage
* %(atts-name)attribute_name% %(atts-type)value_type% Description of the attribute usage

Section: Exposed Functions
h3(tag) my_plugin_func
p(tag-summary). This function will do foo or bar.
*(atts) %(atts-name)Return Value% %(atts-type)return_value_type% Description of the function return value.
* %(atts-name)arg_name% %(atts-type)arg_value_type% Argument description.

Section: Global Variables
h3(global). $my_plugin_global
p(global-summary). This array is set during _blah_ and is false on failure.

Section: Plugin Events
h3(event). my_plugin.event
p(event-summary). This event is called when blah happens.

I will update the formatting as feedback is posted.

Last edited by Manfre (2007-12-29 00:17:33)

jstubbs · Tweet

+1. Excellent idea. Many plugin’s have messed up help text.

Bloke · Tweet

Yep, works for me. Nice one Manfre.

Couple of points:

I don’t think the otherwise awesome ied_plugin_composer accepts textile in the help, so a non-textile template might be required as well. I could be wrong
The current plugin size limit includes help, yes? And quite a few people have had issues installing large plugins; when the help’s removed the plugin installs fine. Although it only assists a minority, I’ve started only giving a TOC or abridged help in larger plugins, with links to full online help. The plugin is of course distributed with a standalone .html help file in case the server is down. I’m sure this isn’t the best use of resources but it’s a workaround for the plugin size/max upload PHP limit. Further compression is an option I suppose (though I’ve no idea how to do it from ied_plugin_composer), but perhaps there should be an abridged template for massive plugins too? The full help, wherever it’s located, should follow the full style template as given above.

And, yes, I could probaly rationalise my plugin help quite a bit :-)

ruud · Tweet

Stef: the plugin size is has a 64kB limit for help and code separately, so help size doesn’t affect the maximum code size. Compression is usually enough to keep it below the upload limit of most webhosts.

Michael: I’d welcome the idea of having better default styling for plugin help, preferably similar to how Textbook styles the help pages for TXP tags. A few comments:

having examples all together works fine for small plugins, but for ZCR (which uses a similar, though slightly different styling than what you propose) I used an example for each tag because that was clearer, IMHO, than having one big chunk of examples.
If a standard is decided upon, the help- prefix for classes could be dropped.
I’d make the plugin title a H1 instead of H2.
If there are installation steps, there may also be de-install/cleanup steps

net-carver · Tweet

Manfre

For larger plugins I think having an optional TOC at the head of page (and top^ links at the side of each major heading or entry in the TOC) might be useful too. I’ve also started including a hyper-linked tag index in my help. Smaller plugins might not need these items.

In summary, how about…

Optional TOC
Summary
Author Contact
License
Plugin dependencies
Installation steps
Optional tag index (hyperlinks to tags)
Tags (and attribute descriptions / example usage)
Exposed functions (for class plugins)
Admin page help
Any other examples

I tend to put examples of tag usage in with the actual tags rather than at the end.

jstubbs · Tweet

net-carver wrote:

I tend to put examples of tag usage in with the actual tags rather than at the end.

This is much easier for users. I find myself looking at specific tags after a plugin is setup. Like in ZCR help – there is a quick setup at the beginning, and then tag examples after each tag. That works best in my view.

I also think an un-install option would be good, or instructions on how to un-install in case any forms etc were created.

Manfre · Tweet

@stef, plugins can be easily changed and adding support for textiling text is simple thanks to the textpattern/lib directory.

@ruud, Inline examples for each tag/function is good and I had that in mind. The examples section was intended more as a “the bigger picture” style example. E.g. a complete ZCR form, instead of just an individual tag. Dropping the “help-” prefix is a good idea.

@steve, I like the idea of ToC and tag index. If all of the sections and tags are identified by class, then these can be auto created when the plugin is compiled.

net-carver · Tweet

Manfre wrote:

@steve, I like the idea of ToC and tag index. If all of the sections and tags are identified by class, then these can be auto created when the plugin is compiled.

Ahah, if you’re heading down the auto-compilation of help sections route, then things could get very useful (I missed that in the OP, sorry.)

In that case you could pull some other information together automatically too like …

the license and author contact details. Perhaps add a plugin[‘license’] field to the plugin template for that etc.
dependencies on other plugins can also be detected by parsing the code block for required plugins or included files that are outside of the normal set of Txp files.

Also, couldn’t some variable substitution be done on a help section if it were in heredoc format inside the main php block in the template and simply echo’d out?

Just brainstorming a little here — so some of the above may seem way off the deep end.

Manfre · Tweet

I added sections for “Global Variables” and “Plugin Events”.

Manfre · Tweet

The CSS styling is currently removed when a plugin is decoded. Here is a 4.0 patch

Txp Network Links

Textpattern Support Forum

2007-12-28 09:09:10

Standardized Plugin Help

2007-12-28 10:29:32

Re: Standardized Plugin Help

2007-12-28 11:37:31

Re: Standardized Plugin Help

2007-12-28 14:07:56

Re: Standardized Plugin Help

2007-12-28 14:36:22

Re: Standardized Plugin Help

2007-12-28 15:01:16

Re: Standardized Plugin Help

2007-12-28 16:30:53

Re: Standardized Plugin Help

2007-12-28 16:45:32

Re: Standardized Plugin Help

2007-12-29 00:09:11

Re: Standardized Plugin Help

2007-12-29 01:23:13

Re: Standardized Plugin Help