soo_plugin_help_viewer: View formatted help text from the plugin cache

jsoo · 2017-03-14 18:30:40

Forked from net-carver’s original sed_plugin_help_viewer. This version adds the ability to preview help text in standalone files, i.e. README.textile, README.markdown, or README.md.

Duplicate files are a hateful business, and there’d be no point to this update if it just meant extra work. The reason for the update is that I already have a similar modification of the textpattern-plugin-template package. Code in one file, help text in another, and the help text serves double duty by also working as a README, for GitHub or for otherwise distributing a package as source files. So for me, it’s less work, and a cleaner workflow.

In short, if you are completely happy with your current plugin development workflow, this plugin isn’t for you. But if you’re still dealing with the old zem template with code and help text in the same file, and if you like the idea of separating the two, please give the template package and this plugin a look.

soo_plugin_help_viewer
My modification of textpattern-plugin-template (make sure it’s the dev branch)

Last edited by jsoo (2017-03-14 18:49:54)

Bloke · 2017-03-15 09:29:16

I think I just found me a new workflow. Spookily enough, before I fixed the bugs you found in zem_tpl the other day, I’d started work on exporting the help text as a separate README.textile file for GitHub. Great minds… :-)

But your implementation is way better and more complete. I wonder, on a related note, could we roll such support into the official template in a backwards-compatiblish way? It’s horribly outdated and could do with some love in the modern age, as well as fixing issues like the one you found the other day with class Textile not loading.

As an aside, here are some of the other things I dislike about the current template setup:

Having to include zem_tpl.php in the current directory and have that inclusion defined in the plugin template. I think a config approach is much better as it could all be defined once. Don’t know the best way to solve it generically, though without breaking people’s existing templates.
Having to define the plugin flags in the template seems redundant. Why not define them in a config file too? Old templates would still work because of the if(!defined), but ones using a config-based template could remove those lines.
It’d be nice if the Textpack content could be injected into the plugin at compilation too, from separate files instead of defined at the top of the file. Not only would this make it easier to copy ‘n’ paste or upload them to share, it would also mean I wouldn’t have to scroll through six languages of strings before I reach the code. See zem_contact_reborn.

Of course, this would mean that ied_plugin_compiler would need to change, but that’s my problem.

Whaddya think: doable?

jsoo · 2017-03-15 10:59:57

I think it is backward compatible with the old template, but I haven’t given it a true test. Will do that.

Ooh, great idea to move the plugin flags to the config too. Indeed, why not move the entire $plugin array over. Then the template itself is just the actual plugin code, except for the if (! defined('txpinterface')) block.

Textpacks, yeah. I do have a couple of plugins with Textpacks but haven’t gotten round to separating those out. Needs to happen.

Bloke · 2017-03-15 11:12:25

You might want to look at some of the work Gocom did, e.g.:

Some good stuff in there, I’m sure. #AvoidWheelReinvention

jsoo · 2017-03-15 11:33:50

Wow. Lots to chew on.

jsoo · 2017-03-15 15:40:18

Pushed a couple of commits to my fork of the template/compiler package; should now work correctly with the default template or my new one, with help text processed only when it should be, and only once. Haven’t moved the $plugin array over to config.php yet, but will get around to it.

Last edited by jsoo (2017-03-15 15:41:35)

jsoo · 2017-03-16 15:37:00

Bloke wrote #304762:

You might want to look at some of the work Gocom did, e.g.:

Look for an already-existing package: that would be too much like good sense. OK, Gocom’s stuff looks fantastic (surprise, surprise), has complete separation of code, help, textpacks, and plugin manifest for the metadata. Php executable wrapper as a CLI. Love it.

There’s also a compiler jmd made some years back, same idea, using a php DocBlock in the code file for the metadata (nice idea), and a makefile for file paths (another nice idea) and with the option of using make for the build. No Textpacks; should be easy to add. Again, looks excellent. I’ve actually had this sitting on my machine for years, but had forgotten it.

I don’t consider my time tweaking zem_tpl.php wasted because it helped me learn my way around the newer parts of the core, but I will certainly be making use of one or both of the above.

You raised the point about backward compatibility, which is of course an essential part of the Txp ethos. But I think in this case a new compiler need not be compatible with old templates; that’s the plugin dev’s choice. All that matters is that any compiler produces the correct output. We should keep the old template and a compatible compiler available on GitHub, but I think we should offer some alternatives, such as the above, too.

Bloke · 2017-03-16 16:24:18

jsoo wrote #304809:

a new compiler need not be compatible with old templates

Absolutely. If we’re starting afresh, then cool.

All that matters is that any compiler produces the correct output.

Okay, and here’s where it gets murky. What is “correct output”? Today, it’s a .txt file containing (optionally gzipped) BASE64 content comprising a serialised array of fields that get loaded into the DB. Tomorrow…? Who knows. Maybe that format has had its day and we should embrace something a bit more… modern?

Advantages of the single .txt file:

Simple to transmit, automatically email safe.
Simple to install.

Downsides:

Can’t bundle up additional resources unless they’re part of the plugin code.
Serialization is horrible.

Jukka favours having metadata files a la Composer and keeping the assets separate. I like that for development, then everything’s compiled for distribution. Currently, to the same compatible format we’ve used for years.

Could we expand the template format here so we could include more fields? Even though (at the moment) they don’t feature in the database schema, they could one day. Or could just be for presentational purposes for now. I’d love to start building in some way of indicating which version of Txp a plugin is built for. Doesn’t mean it won’t work on later versions, but it might. It provides a baseline and simply displaying that somewhere — even just in the header of the .txt file — means potentially fewer surprises.

Now, Composer does that for us with the dependency management. I don’t use Composer (I probably should). I don’t think it should be a requirement as it’s another hurdle. But could Txp take advantage of being a Composer resource on Packagist? Perhaps. I think Robert put together a version on his GitHub repo somewhere that used it. That gives developers the option to write plugins targeting certain version of Txp. And consumers the option to pull the correct version of a plugin for their installed Txp.

I did start a version of the Plugin Composer, btw, with support for all this and got most of the way there. Just need an excuse to finish it off.

Is this an opportunity to tweak the template and / or tweak what it outputs to be more useful? If we need to alter the installation process slightly while still keeping everything simple, that’s fine. i.e. we might decide that serialising content is bad and we JSON encode it instead, because it’s a better transport mechanism. We can alter core to detect this. In fact, I’d say we should have some header info in the template and the distributed .txt file that indicates which system was used to build it. That way we can read that on installation and pick the right unpacking/installation mechanism. Could (should) even version it.

Lots to think about. But I’m not averse to change if it makes things a) easier to develop, b) easier to deploy, c) easier to install.

jsoo · 2017-03-16 16:46:16

Ah, cans of worms within cans of worms. So many ways this could be done. It has always seemed odd to me that plugin code is pulled from the db rather than an include directory somewhere; i.e. installing a plugin would be more akin to uploading an image or file. But whatever the compiled format needs to be, separate assets a win-win, methinks.

Bloke · 2017-03-16 16:52:39

jsoo wrote #304818:

It has always seemed odd to me that plugin code is pulled from the db rather than an include directory somewhere.

We support both. Installation has merits (lifecycle management events, for instance). Using the plugin cache dir means no compilation step and users can do external version management on the files. But no Textpack integration (yet) unless using the Plugin Composer, which supports it.

But whatever the compiled format needs to be, separate assets a win-win, methinks.

I concur.

Textpattern CMS

Textpattern CMS support forum

#1 2017-03-14 18:30:40