Symphony.

The new XSLT Utilities repository is going to be great. We really need to migrate the existing utilities across. I've moved a few of mine over, and in doing so have used a basic documenting syntax at the top of each:

Example:
http://www.getsymphony.com/download/xslt-utilities/view/20486/

<!--
Name: Number To Words
Version: 1.0
Author: Nick Dunn <nick@nick-dunn.co.uk>
URL: http://symphony21.com/downloads/xslt/file/20486/

Parameters:
* number (required) an integer
* resolution (optional) round 'number' to the nearest 'resolution', e.g. '10', '50, '1000' etc. Use '-1' to allow the template to choose an appropriate rounding resolution
* minimum (optional) if the number is less than this the returned string will be 'less than $number'
* maximum (optional) if the number is more than this the returned string will be 'more than $number'

Further usage examples:
http://symphony21.com/forum/discussions/763/
-->

Similar to a README for an Extension, I propose adopting this (or similar syntax) for all utilities so that they remain consistent.

The URL points back to its home on the Symphony site. This example includes a link back to the forum announcement discussion, but I'd suggest this should be avoided. The forum thread for each utility/extension often becomes intolerably lengthy, so I'd encourage a new thread for each separate discussion.

Thoughts?

I endorse this :)

I like standardization, but maybe we should further emphasize headings to avoid confusion when someone uses multiple paragraphs for one section.

How about something like this:

<!--
Name: Number To Words
Version: 1.0
Author: Nick Dunn <nick@nick-dunn.co.uk>
URL: http://symphony21.com/downloads/xslt/file/20486/

Parameters:
-------------------------------------------------------
* number (required) an integer
* resolution (optional) round 'number' to the nearest 'resolution', e.g. '10', '50, '1000' etc. Use '-1' to allow the template to choose an appropriate rounding resolution
* minimum (optional) if the number is less than this the returned string will be 'less than $number'
* maximum (optional) if the number is more than this the returned string will be 'more than $number'

Further usage examples:
-------------------------------------------------------
http://symphony21.com/forum/discussions/763/
-->

Works for me.

I’m wondering whether it’d be worth having (optional) Gist integration as well. Would save people having to update them in both places.

Heh, I just removed mine from Gist favouring the XSLT Utilities section instead.

We looked into using Gist for the XSLT section, but since GitHub limits API calls to 60 per minute, we decided we could release the new site quicker if we just used a Symphony-based solution. Gist integration is still a definite possibility in future, but we’ll need to fashion some sort of caching system for it first.

Ah, fair enough, though I would’ve thought you could use the the JS embed option for showing the Gists—does the API limit apply to those?

This is strictly my personal opinion – I don’t really like using gist for my XSLT utilities. Version control err on the side of overkill for me. If today we’re talking about multi-file super utilities, then version control would factor in. But even then, neither gist nor our solution would be adequate. I’d be using Git for that.

@carsten, unfortunately double-hyphens inside comments are not valid, so will throw an XML error. I suggest leaving this for now — multiple paragraphs would work so long as the author clearly labels things.

Gist is great for versioning but it’s always felt temporary, like Pastie, as if my code could expire at any time. A dedicated home on the Symphony site for Utilities/XSLT does make sense in my mind.

I’d err on the side of consistency. If all the other code offerings on the site uses Git, then I’d also use it for the XSLT Utilities.

On a counter note, I still can’t figure out Git. (I think I can handle Gist, though.) I’m not a Terminal guy, so even the Git for dipshits tutorials intimidate me.

On a counter note, I still can’t figure out Git.

You’re not alone. For this very reason I don’t think XSLT utilities should use Git.

In addition to what Allen has stated, it’s okay to expect extension developers to utilize Git but for many XSLT gurus it may be seen as a barrier.

On a counter note, I still can’t figure out Git.

A perfect reason for a dedicated article in the documentation about using Git and Github, with specific reference to Symphony and Extensions.

The XSLT Utilities part of this site is an incredibly low barrier to entry.

For this very reason I don’t think XSLT utilities should use Git.

I totally agree. I’m not saying you should have to use Gist, just that it would be nice to have an either/or for the people that do use GitHub.

I haven’t really used Gist much but I’d rather keep my various code snippets in one place and Gist integration would make that easier.

Hey Allen,

You should post the serial list utilities you sent me a while back. They’re here. Simple but quite useful…

I will need to first modify the utility so that it won’t need to modify the match pattern. I think the rule for utilities should be to not have to modify the code. That way, it allows users to drop in a newer version (presumably bugs fixes) and expect it to work.

I’ve done a little searching and have found a few alternatives to commenting XSLT documents. If we adopt a standard then we’d be able to parse comments into standalone documentation. Here’s what I’ve found:

• XSLStyle
• pyXSLdoc
• XSLTdoc
• Document Your XSLT article
• DocBook syntax
• XML processing instructions?
• discussion

This is more a reference list to serve as a reminder for the future. We’re getting API docs for Symphony 2.2 (PHP code) and JavaScript soon to follow, so the next logical step is to document XSLT in a standard way too.

One for a rainy day.

Using Github for XSLT Utilities has been discussed some time ago but I'd like to revisit the discussion for a moment.

My guess would be that more and more people are getting familiar with GitHub, also since it has become the de facto repository for extensions. Storing Utilities on Github (normally, or as Gists) gives us many of the same advantages as we currently have with the Symphony extensions: one can easily update or fork them and issue a pull-request for improvements.

It's not so much about version control but about ease of updating/improving/portability etc. I'd, for example, like to maintain one version of .gitmodules for my 'default' Symphony extensions and utilities.

Some people (@zimmen, @phoque, etc) are recently also (at least) linking or storing their utilities as Gists and I would propose this to become a preferred 'standard' for Symphony Utilities just like Extensions.

It is clear to me that there are issues with such a third-party integration (API limits etc) but these issues have been addressed with extensions, it seems, so why not for Utilities?

Maybe this could be added to the Symphony CMS website improvements? I added a Suggestion Issue (on GitHub ;)

Yes, I like this idea. I know that Stephen and Marco have been working over the last few months on a JSBin-type service for running XSLT tests against XML documents that uses Gist as its backend. Whether or not this allows users to store XSLT as "finished" pieces I don't know.

Presently the UI of managing gists is really poor — it is difficult to find a gist I created 6 months ago. In this respect, I worry that a gist is something quite temporary, whereas a named repository is relatively permanent.

The benefit of storing as Gists:

• can comprise multiple files (not just XML... I'm thinking of the pagination utility and its CSS)
• other users can fork and modify as they please
• embed code provided

Disadvantages:

• locked to Github users only for commenting/forking
• no formal pull requests, so merging code from forks is a process of direct communication

So… why not adding Utilities as complete Github git repos, just as extensions?

Sure, it seems a little overkill but it gives us many advantages: cloning, pull-requests, tickets, downloadable packages, etc.