KnitML

KnitML 0.3 Released

I am very happy to announce that KnitML 0.3 has been released. This release includes a much-needed user's guide and solidifies support for the KnitML Expression Language (a.k.a. GroovyKnit). GroovyKnit should make writing KnitML files a breeze.

Give it a try and let me know what you think!

Upcoming KnitML 0.3 release

After a bit of a hiatus to concentrate on a software release for work (and a nice vacation to the Pacific Northwest), I am now gearing up to release KnitML 0.3, hopefully within a week. Not only will it include a series of bug fixes and enhancements, but I hope to have a fully annotated schema as well as more documentation and formality of the new GroovyKnit syntax.

I'll certainly keep you posted.

KnitML 0.2 released

KnitML 0.2 has been released! New features include:

support for multi-color knitting, including schema changes and a new color swatch sample KnitML file
more complete internationalization support
support for binding off
Groovy support
first cut of a knitting pattern domain-specific language - much shorter and more intuitive than coding XML directly

Here is an example of how to apply the domain-specific language. Instead of writing this:

You can write it like this:

round { repeatToEnd { p 1; k 2; p 1 } }
round { knitToEnd() }

I'll do a separate posting about writing in this expression language, as there are a few quirks to know about the way Groovy expresses functions. Once you learn the rules, though, it's free sailing.

Anyways, give the new release a go and let me know what you think!

Peeling Back the Onion: KnitML Core

Now that you have hopefully had the chance to play with KnitML, I thought I'd blog a mini-series about each component to give you a better understanding of how everything works.

The core project provides building blocks for defining and parsing KnitML documents. This includes:

XML schemas to define the KnitML syntax
Knitting extensions to the JSR-275 Units specification
Utilities for working with KnitML documents

The XML schemas

The XML schemas define the syntax of a KnitML document. This includes data type and data structure definitions. Data types are usually primitive values such as numbers, strings, and booleans (or subsets of these types), while data structure refers to the elements that can appear within the body of the element.

The body of the element can only contain a positive integer because it indicates the number of stitches to knit. This is an example of a data type definition. The body of the element, however, must contain one or more elements within it, and the ordering may be important. This is an example of a data structure definition.

You can validate the syntax of a KnitML document with most XML editors. The schema location information is located in the root element of the KnitML document (). You can also perform syntactic validation by passing the -checksyntax option to the knitml command line:

knitml validatePattern pattern.xml -checksyntax

Keep in mind that syntactic validation is different from semantic validation. I'll cover semantic validation in my next post in this series.

The JSR-275 Units Specification

JSR-275 is a Java community effort which defines a standard measurement framework, and JScience provides a reference implementation for JSR-275. I have chosen to use this framework as a basis for converting knitting measurements between English and metric systems. KnitML Core extends upon JSR-275 to provide support for converting between US and standard needle sizes as well as definitions for gauge units (st/in, st/cm, row/in, row/cm).

Utilities

The utilities provide code support for common concepts used in other components. This includes common exceptions and enumerations, constants for XML elements and attributes, and parsing utilities. KnitML uses dom4j, a Java API for working with XML documents as an in-memory tree structure. KnitML Core builds on dom4j to provide additional support for KnitML-specific data type parsing, methods such as isKnittingOperation() and getGaugeForElement().

KnitML Core's dependencies

The KnitML Core project, like the rest of the KnitML projects, are built using Maven 2. This means that you can identify a project's dependencies on external components simply by examining the pom.xml file in the root directory of each component. KnitML depends on Commons Lang and Commons Collections, dom4j, and JScience. In the next release, KnitML will also depend on Spring Core and Spring Beans as these components provide XML schema resolution tools useful for offline schema lookups.

KnitML 0.1.1 released

This is a minor enhancement / bugfix release which provides the following functionality:

Java 1.5 compatible
Shell script for *nix environment (tested using Cygwin for Windows)
Full featured validator no longer requires "needle1" and "needle2"

So now all of you running 32-bit Mac OS can celebrate!

KnitML 0.1 Released!

Ladies and gentleman, we have a release! I have put it up on SourceForge. Please download it and let me know what you think. Choose your download format (tar.gz or .zip) and unpack it to the directory of your choice. All files in the archive start with the knitml-0.1 directory, so you can unpack it into a generic directory (such as C:\projects, for instance).

Once you've unpacked the files, read the README.txt in the root directory. It will tell you how to set up your environment so that you can run the knitml command from any directory. Take a look at the samples/basic-sock directory to see how the sample is structured and to try out the knitml executable.

The command you'll most be interested in is:
knitml validateAndRender filename-to-process

And to capture the output to a file:
knitml validateAndRender filename-to-process -output pattern.txt

Known limitations

Because I forgot to remove some hard-coded meta information from the validator, there is a limitation that you can only use needles with an ID of "needle1" and/or "needle2" and pattern messages in a file (or files) named pattern-messages.properties. The sample conforms to these limitations, so please model any patterns you write after this fashion (for now, until a bugfix release comes out). Hopefully, you won't need to use more than 2 needles right away in your patterns. Also, the 'knitml' executable is only currently available as a Windows batch file. If you are running on a *nix platform, you will have to call the Java program manually. If someone would like to contribute a *nix script, I will be more than happy to include it in a future release.

Development and Contributions

Please submit bugs and feature requests to our issue tracker. You have to sign up for an account, but I promise it's quick and painless, and your e-mail address won't be used for anything other than notifications of the progress of issues you submit. Please, please, please provide your feedback and help to better the KnitML project!

If you are interested in downloading the source code (hopefully with the intent of contributing), it is stored at the Sourceforge Subversion repository. The SVN URL (for access with an SVN client) is https://knitml.svn.sourceforge.net/svnroot/knitml. I apologize but I have not been able to get my assembly tool to give me a reliable source package yet. I may assemble something manually and upload it in the coming days.

The project is built with Maven 2. I use Eclipse to develop KnitML, so all of the required Eclipse artifacts are also in the repository. I also use the Maven plugin for Eclipse, and I highly recommend it. Note that you can still use a different IDE to develop KnitML, it's just that the artifacts are not (as yet) checked in.

The project is organized into several modules:

knitml-parent: top-level meta-information about the project, including build configuration
knitml-core: contains XML schemas and core processing code
knitml-validation: provides a mechanism to verify that a KnitML pattern is knittable
knitml-pattern-renderer: produces a human-readable pattern from a KnitML pattern
knitml-tools: provides executable classes to bind the modules together

I recommend downloading all of the modules to start with. The development stream for each module is located under: module_name/trunk.

Thanks for everyone's continued support to get us to a 0.1 release!

KnitML 0.1 achieved!

After several months of planning, designing, coding, and debugging (as well as an almost two month break on the project completely), I can confidently say that both the validator and the pattern renderer for the basic sock pattern works! This means that KnitML 0.1 has been accomplished! Thanks to everyone who has participated thus far.

I will be packaging this up into something far more useful than its current state. You'll get a Java JAR out of this with directions for use. Instructions will be forthcoming once I get the JAR built.

New Bug Tracker

First, I would like to wish everyone and their family very happy holidays! We just received 5 inches of snow here in Chicago, and it's quite delightful to look at.

You may have noticed the new KnitML Issues Tracker link on the sidebar. Matt, our fearless web admin, has installed Bugzilla, which is a vast improvement from what SourceForge was offering. Bugzilla will be KnitML's central repository for issues.

Some of you may not care for Bugzilla, so I have to let you know that it was not my first choice. Ideally I wanted JIRA, but our hosting service here at knitml.com doesn't support Java. We tried out Mantis, which is PHP-based. The interface was nicer than Bugzilla, but we could not get it to integrate with Mylyn, a task-based plugin for Eclipse which is an integration point I think is necessary. Since the Mylyn project grew up using Bugzilla, and integration with it was incredibly simple, it seemed like a no-brainer.

That said, Matt has done everything easy he can to make the web interface a bit more bearable. He removed the picture of a nasty-looking microscopic bug which comes with the default screens. He also installed the Flat Green skin, which makes Bugzilla look a lot more Google-esque than the traditional I-was-clearly-developed-by-hardcore-computer-science-geeks skin (though I think they just call it the "default" skin).

If you still object to the web interface, I would highly encourage you to try out Mylyn 2.0. It comes with the newest Eclipse Europa package. You can interact with Bugzilla completely within the confines of Mylyn and Eclipse without ever having to go the website. It's quite slick.

You do need to create an account to report bugs. This is mostly so that you can be informed of the progress of bugs through e-mail if you prefer. Your information will be completely private. I promise I won't sell your e-mail address to anyone and I won't use it to communicate with you directly without your permission.

Now... bring on the bugs!

MusicXML: A Case Study

In perusing the web recently, I stumbled across MusicXML's successful attempt to standardize an interchange format for many different music softwares. They have several recommendations to make regarding incubating standards for a niche market. Read the full article here, or just the highlights from the article below:

Apply usability techniques to language design in the same way that you would to GUI design. Use terms that domain experts understand. Where possible, avoid introducing concepts that are specific to applications in the domain, rather than to the domain itself.

Develop the format together with software that reads and writes the format. Use evolutionary delivery to deliver early versions of both the format and the software, with frequent iterations to get both working well together. This particularly helps for meeting the twin goals of completeness and usability.

Make sure that the format can exchange data in both directions with at least one market leader in your application area. Do this as early as possible in your development process. Do not expect the market leaders to do this for you.

Market to other developers who would get a business benefit from using your format. This will be difficult until your format can exchange data with a market leader.

Give format developers good support. Involve the development community in the design of the format. Be responsive to developers who are using early versions of your format and translation software.

Avoid overhead. In a small market like music notation software, organizations like ISO and OASIS can be too costly in both time and money for even the largest industry players. Following the model of Adobe's PDF format - an open format under single company control - can be more effective in these situations.

In short, I think our instincts for what to do and how to do it have been right, or at least have been justified. I definitely see their point about standards organizations. Besides, they don't seem to want to talk to me anyways. :)

What You Can Do!

If you are looking for ways to help (and I know that many of you are), here are some things that you could do:

Get familiar with XML, XML Schema, and what I have done so far with KnitML. You certainly won't need the nitty-gritty details of XML Schema, but at least enough to understand which options are available.
Take your favorite patterns and attempt to convert them to KnitML (as I have done with the sock pattern). If there are things that are missing from the XML Schema that you need, add a feature request on the SourceForge tracker. This will help us fill out the spec to emcompass all types of knitting. If it works and validates, I'll publish the pattern on the website.
If you are a code geek, install a Java JRE and try to run the validator. Get familiar with the code base and make recommendations for improvement.
If you are multi-lingual, translate the instructions.properties file into your favorite language using the conventions of that language. See if you can get the renderer to make the pattern look like what a normal pattern in that language would look like. If something doesn't work, submit a bug or feature request.
Start building your own software that does something cool.

The possibilities really are endless. If there is anything else you'd like to do, including helping me refine the pattern renderer or expand the validator, please let me know.

Thanks for everyone's support!