Changes in Textile v2.5

[netcarver]

Hello folks,

The next release of textile (v2.5) is going to see some major changes to the codebase and a few minor additions to its abilities to handle text. The changes outlined here are not yet committed to the dev branch of netcaver/textile but (Now committed) I want to post about this in advance so any developers here can get a feel for what will be changing and see if it impacts them (to track what is already committed to the dev branch for v2.5 you check the changelog.)

As I'll be taking over responsibility for maintaining the textile text formatters with this release, I'll also take care of making sure these code changes don't impact end users of the textile in PW. However: if there any devs reading this who use textile in other work they might be interested in the rest of this.

To facilitate textile’s uptake in other projects & to make it plain easier to read, I'm moving the code towards PSR-2 compatibility. Although I don't necessarily agree with everything in the PSR-2 standard, I will be adopting it for textile because...

• textile has used no coding standard to date and has had many contributors who have all used different styles & consequently the coding style (or lack of it) reflects this and needs some sanity restored to it.
  
• It gives people who may contribute to textile a standard to work to.
  
• I have been advised that a minimum of PSR-1 compatibility is required for textile's uptake in at least one other CMS.
  

So how might these changes bite your installation? Here's a few ways...

First potential problem: Are you overriding textile's defines to customize something?

As PSR-1 (needed for PSR-2) doesn't particularly like code declarations & side effects (such as the #defines that pepper textile) in the same file, I need to know what use, if any, folks are making of the existing txt_ defines listed here as they will be going. If you are using them, you will need to start calling a new method setSymbol('name', 'value') prior to calling TextileThis() or TextileRestricted() and drop the defines as textile will no longer be using them at all. NB. the 'name' to pass into setSymbol() is as shown in the link above without the leading 'txt_' which is no longer needed as the names will no longer be in global scope.

If you are using textile in exactly its default configuration with respect to defines there is nothing to worry about so far.

Next: Using a define called 'hu' to make all relative image paths absolute.

This is only likely to impact the use of textile in Textpattern CMS (it's original parent project.) Textpattern CMS uses a define called 'hu' to point to its root path and if textile finds a define called hu it uses that to prefix all root-relative image paths turning them into absolute paths. Now that textile is breaking free from its Textpattern CMS heritage, I think it's time to break this hidden coupling between the two and instead replace it with a generic (and explicit) setRelativeImagePrefix() method, allowing other projects to use relative image path prefixing if they need to without resorting to using the 'hu' define and without the possibility of a name conflict if they already happen to be using a define called 'hu' for something else.

If your project doesn't use any define called 'hu' the above won't be a problem for you.

Finally: Still using PHP4?

I thought not, but I have to cover this anyway. Next up is PSR-2's requirement for explicit visibility on all properties and methods. As textile comes from a PHP4 heritage it has never had these. A quick look at my stats for PHP versions across hosts show that ~79% of hosts run PHP of some kind and that ~76% are PHP5 or better. Needless to say, PHP4 support is going.

But even if you are running PHP5+ this change to the textile codebase will bite you if...

1. you are calling any methods other than the constructor method, TextileThis() and TextileRestricted().
   
2. you are accessing any of the class properties. These will all become either protected or private and most will have no set or get methods.
   

I figure that for most projects using textile there will be no issues but please let me know if you are going to get bitten by any of the above and if you know of other devs who use textile in their projects, please give them a heads-up.

[Adam Kiss]

I know that this might be weird, but could you add support for MD-style headers?

   /#{1,6}/

That would be superb!

---

Also, I know it might be too much, but could you checkout CodeMirror ans see whether it would be feasible for you to create Textile mode for it? Thanks

[netcarver]

Hi Adam,

thanks for the feedback. Feel free to open an issue on the netcarver/textile repo for any feature requests or ideas you have.

Going beyond v2.5 I'm considering adding a plugin system to textile, called "textplugs", and having a textplug specifically for MD compatibility but I don't want to make MD compatibility part of the textile core.

[netcarver]

Just a quick update. I've now pushed a preview of the changed code to a new 'nr' (next-release) branch. Feel free to post comments, suggestions or questions here or raise issues over on the repo itself.

I've actually started documenting the methods too -- something that will be ongoing over the next few point releases.

[netcarver]

Update: new versions (v2.5.0 and v3.5.0) now available. Yes, two versions. Both are feature compatible (at least they are at the moment) but differ in that v2.5.0 is not PSR-0 compatible as it doesn't use PHP5.3's namespace facilities. v2.5.0 only needs PHP5+ and is therefore suitable for projects targeting older versions of PHP.

v3.5.0 is PSR-0/1/2 compliant and needs PHP5.3+ for namespace support.

@Ryan, I'll be in touch soon about taking over maintenance of the Textile text-formatting modules for PW.