The KnitML project's goal is to define and promote the adoption of a standard content model for knitting patterns. By developing a community-supported specification and providing basic rendering and transformation tools, the project aims to make KnitML easy to use and valuable to the knitter.

Knitting patterns are algorithms as much as they are documents. Consequently, it is important that a computer to be able to understand the algorithm so that it can make decisions. At the same time, a pattern must be able to be rendered into a published pattern in human-readable form. A KnitML pattern, therefore, is a formalization of the algorithm required to produce a knitted object, composed in a way that can still be rendered as a comprehensible published pattern.

The tools provided by the KnitML Project are meant to show the value of KnitML to the knitting community by demonstrating the advantages to standardizing on a content model. They are by no means exhaustive. Independent efforts to write software which understands KnitML patterns (such as the Knitter project) are already underway.

KnitML patterns are expressed primarily using a technology called XML (Extensible Markup Language). XML is an international standard for expressing custom document markup. KnitML provides validation rules to an XML parser (in the form of a schema) which ensures that the knitting pattern follows the expected syntax. If you use an XML authoring tool to develop KnitML patterns, the software's suggestions and completion tools will help you more quickly gain an understanding of the XML syntax.

XML is well suited to serve as an interchange format for software, though it is not without its disadvantages. For one, it's not a particularly compact syntax, nor does it flow, read, or even resemble a traditional knitting pattern. While XML is a language that is human readable, it is not intended to be directly edited by humans. Ideally, a KnitML authoring tool would do this and make pattern designers' lives easier.

The Knitting Expression Language, or KnittingEL, attempts to provide a far easier way to express a KnitML pattern. A KnittingEL pattern uses familiar knitting pattern language constructs and is more free form in nature. As a result, it looks more like a published knitting pattern than its XML counterpart. KnittingEL is not intended to be a software interchange format; it is a pattern authoring tool only. Patterns written in KnittingEL are converted to XML before passed to supporting software (such as the validator and the pattern renderer).

While we encourage all patterns to be developed in KnittingEL, tooling support is limited to basic text editing. Because of this, it's pretty easy to create KEL files that will produce invalid XML files. XML tooling is far more extensive and will better be able to guide the pattern designer to create a valid pattern.

KnitML requires Java 1.5 (or higher) to run. If you do not have Java 1.5 installed, please visit the Sun website to download it (http://java.sun.com).

To set up your machine to run the knitml executable, you must:

For Windows XP, you can set environment variables from the Start menu. Select Settings, then Control Panel, then System. Select the Advanced tab, then press the Environment Variables button, highlight the System Variable (or User Variable) with the name you want, click Edit, add or append the desired value, then click OK twice. (Whew!)

The samples directory contains several different patterns to showcase the both XML and KnittingEL patterns:

The conf directory contains files which configure the way KnitML runs. It includes logging configuration as well as several files which configure the validator and pattern renderer. The conf directory is added to the classpath when a knitml command is executed.

The pattern renderer uses a set of property files (called a resource bundle) built into the module that allow rendering in different languages. Currently, KnitML provides support for both English and Spanish rendering. This will expand as people contribute more languages. If you would like to add support for a new language, see the section called “Adding Support for a New Language”.

You can use your own property file to further customize how a pattern will look when it is rendered. See the section called “Personalizing Patterns” for guidance.

To process a KnitML file in XML format, first change to the directory where your XML file is located, then run one of the following commands:

If the -output option is not specified, the result will be sent to the screen (i.e. "standard out"). The -checksyntax option performs XML schema validation against the provided file. You do not need to be connected to the Internet to check the syntax, as the software is configured to resolve the XML schemas provided with the KnitML core JAR file.

You can also use the following shortcuts: r for render, v for validate, vr for validateAndRender.

To process a KnitML file in KEL format, first change to the directory where the KEL file is located, then run the appropriate KnitML command:

-output and -checksyntax behave as described in the previous section.

You can also use the following shortcuts: c for convert, cv for convertAndValidate, cvr for convertValidateAndRender.

The Knitting Expression Language (formerly known as GroovyKnit) is based on the Groovy programming language and GroovyMarkup architecture (http://groovy.codehaus.org/GroovyMarkup). Elements are specified by name, and sub-elements go between curly braces following the name. So this in KnittingEL:

pattern {
  generalInformation
}

looks like this in XML:

<pattern>
  <general-information/>
</pattern>

generalInformation in KnittingEL became general-information in XML because generalInformation is a defined KnittingEL function that acts as an intermediary to the XML format to increase readability. In this case, it simply transforms its name to general-information, as you cannot use dashed names in KnittingEL without quoting them. So while you could also do the following to achieve the same result, it's not quite as readable.

pattern {
  'general-information'
}

See Table B.1, “Defined Expression Language Functions” for a complete list of KnittingEL functions.

You have the option to capitalize the first letter of any and all KnittingEL functions. So the following would produce the same XML:

Pattern {
  GeneralInformation
}

In many cases, this is more readable.

To specify an XML element's value as text, simply include it as a parameter. This:

row {
  knit (3)
}

Becomes:

<row>
  <knit>3</knit>
</row>

Note that any of the samples below will produce the same XML as above (this is not an exhaustive list of possibilities):

row {
  knit 3
}

Row {
  Knit 3
}

row { knit 3 }

row { k 3 }

row { k3 }

Row: k3

The first three examples show that line placement inside of curly braces isn't crucial, as long as the method name and its arguments (which occur before the curly braces) are on the same line^[1]. The last three examples use k as a shorthand for knit. k is a defined KnittingEL function which expands to the knit element. The KnittingEL parser is smart enough to recognize that, since k3 ends with a number, the number belongs as an argument to the k method rather than part of the method name.

To express several knitting operations in a row, you can write them in any of the following ways:

row {
  knit 3
  purl 3
}

row { knit 3, purl 3 }

row ( k3, p3 }

row: k3, p3

Row: k3, p3

And you'll get this:

<row>
  <knit>3</knit>
  <purl>3</purl>
</row>

Note that you can use the : syntax to define a row instead of the brace notation, in which case the entire row must be defined on the same line. If you have a more complex row to define that needs to be split into multiple lines, use the {}s instead.

You can use the : syntax for any of the following functions: row, round, nextRow, nextRound, shortRow. The : syntax used with other functions exists for language purposes only and is simply ignored (producing the same effect as if it were omitted).

KnittingEL also defines shorthands for common operations. Here are a few:

row { k to end }

<row>
  <repeat until="end">
    <knit/>
  </repeat>
</row>                

round { k5 }

<row type="round">
  <knit>5</knit>

shortRow { k5, turn }

<row short="true">
  <knit>5</knit>
  <turn/>
</row>

An element's attributes appear before the curly braces in a series of name/value pairs in a bracket (called a Map):

yarnType [brand:'Cotton Classic', weight:'worsted'] { ... }

It's very common for an element to have an ID attribute, so there is often a function shorthand. For example, the following three lines are equivalent:

yarnType 'my-yarn' [brand:'Cotton Classic', weight:'worsted']
yarnType [id:'my-yarn', brand:'Cotton Classic', weight:'worsted']
<yarn-type id="my-yarn" brand="Cotton Classic" weight="worsted"/>

For this example, we will compose the KnitML pattern using the KnittingEL syntax. The pattern is for a simple 4x4 in square knitted in stockinette stitch.

Create a file name simple-square.kel. We will start by defining the pattern element, the root element for all KnitML patterns. Since we're not internationalizing this pattern, we'll specify that it was written in 'en' (the ISO-639 Language Code for English).

Pattern 'en' {}

Next, we'll add some header information about the pattern to a generalInformation element within the pattern element.

Pattern 'en' {
  GeneralInformation {}
}

Let's give the pattern a name. Name, description, author, etc. go under generalInformation. Anything that should be interpreted as a literal value (for instance, a string of text) should be in single quotes.

Pattern 'en' {
  GeneralInformation {
    Name: 'Simple Square'
    Description: 'A simple square'
    Dimensions: '4 in by 4 in'
  }
}

Gauge also goes here. We'll indicate that the gauge swatch should be knit in stockinette at 6 stitches to the inch and 6 rows to the inch.

Pattern 'en' {
  GeneralInformation {
    Name: 'Simple Square'
    Description: 'A simple square'
    Dimensions: '4 in by 4 in'
    Gauge 'stockinette' {
      StitchGauge: 6 stitchesPerInch
      RowGauge: 6 rowsPerInch
    }
  }
}

The colon after the function name is optional. It increases readability in this case^[2].

Let's move on to the next section. We also need some supplies to knit this pattern. Generally a knitter needs needles and yarn, and needs to know what type of each the pattern calls for. In this case, we're not particularly picky about the yarn (as long as it is plausible for obtaining gauge). The only thing we are going to specify is that the weight should be worsted. Likewise, we are going to specify using a size US 4 circular needle of any length.

Pattern 'en' {
  GeneralInformation { ... }
  Supplies {
    Yarns {
      YarnType 'the-yarn' [weight:'worsted']
    }
    Needles {
      needleType 'size-4' circular { size: 4 US }
      needle 'the-needle' [typeref:'size-4']
    }
  }
}

First we added a yarns sub-element to the supplies element. This is where the yarns that will be used in the pattern are defined. Both yarn types (e.g. brand, weight, etc.) and yarn colors of a specific type may appear. In this case, we are only using one type of yarn (with an identifier of 'worsted-weight-yarn' so that we can refer to it later in the pattern if need be). As we don't care about color, there are no yarn elements to define.

Similarly, we have a needles element where all of the needles that will be used in the pattern are defined. Both needle types (e.g. DPN, circular, and other attributes) and number of needles of a particular needle type must be defined. Here we define one needle type we're identifying as 'size-4'. It's a circular needle ('circular') and its size is US 4. We also define that we need one needle of type 'size-4' and we're going to call that needle 'the-needle' (since this project only uses one needle).

Now we will add directions.

Pattern 'en' {
  ...
  Directions {}
}

Since our gauge is 6 stitches to the inch and we want to knit a 4-inch square, the first thing to do is to cast on 24 stitches (6 times 4). You can specify a cast-on method if desired. In this case, we'll specify that the knitter should use the long-tail cast on.

Pattern 'en' {
  ...
  Directions {
    CastOn 24 'long-tail'
  }
}

Stockinette stitch is a two-row repeat when knitting flat. The first row is all knit, and the second is all purled.

Pattern 'en' {
  ...
  Directions {
    CastOn 24 'long-tail'
    Row 1: k to end
    Row 2: p to end
  }
}

Since the project's dimensions should be 4 inches tall as well as wide, we don't want to have to write out 22 more rows of the same two rows. So we will declare rows 1 and 2 to be an instruction, give that instruction an identifier ('stockinette-st'), and then repeat it a certain number of times. In this case, we will repeat the two stockinette rows until the project measures 4 inches. KnitML also calculates row numbers for you if not provided, so we will remove them.

Pattern 'en' {
  ...
  Directions {
    CastOn 24 'long-tail'
    Instruction 'stockinette-st' {
      Row: k to end
      Row: p to end
    }
    Repeat 'stockinette-st' until measures 4 in
  }
}

until measures are keywords which inform the KnittingEL processor to construct the particular XML form when an instruction is repeated to a measurement. There are various other keywords in the KnittingEL. See the appendix for a list of them.

Now that we've reached 4 inches, we will finish the project by binding off all stitches.

Pattern 'en' {
  ...
  Directions {
    CastOn 24 'long-tail'
    Instruction 'stockinette-repeat' {
      Row: k to end
      Row: p to end
    }
    Repeat 'stockinette-st' until measures 4 in
    Row: BindOff all sts
  }
}

That's all there is to it! The complete pattern looks like this:

Pattern 'en' {
  GeneralInformation {
    Name: 'Simple Square'
    Description: 'A simple square'
    Dimensions: '4 in by 4 in'
    Gauge 'stockinette' {
      StitchGauge: 6 stitchesPerInch
      RowGauge: 6 rowsPerInch
    }
  }
  Supplies {
    Yarns {
      YarnType 'the-yarn' [weight:'worsted']
    }
    Needles {
      NeedleType 'size-4' circular { size: 4 US }
      Needle 'the-needle' [typeref:'size-4']
    }
  }
  Directions {
    CastOn 24 'long-tail'
    Instruction 'stockinette-st' {
      Row: k to end
      Row: p to end
    }
    Repeat 'stockinette-st' until measures 4 in
    Row: BindOff all sts
  }
}

If you run this through the basic text rendering program, you'll get this:

Simple Square
A simple square

Stitch Gauge: 6 st/in
Row Gauge: 6 row/in

Yarn:
    worsted weight

Needles:
    1 circular needle size 4 US (3.5 mm)

Directions
----------
Using the long-tail method, cast on 24 stitches.
Row 1: Knit
Row 2: Purl
Repeat rows 1-2 for 4 in.
Row 25: Bind off all stitches

This may not appear to be worth all of the trouble, but keep a few things in mind. First of all, the pattern has been "test knit." This means If there were too many or two few stitches for any given row, the validator would raise an error. This can be very helpful because it can catch certain kinds of errata immediately. The validator also fills in missing information as it's being knit. Notice that all of the rows have been assigned numbers.^[3]

Second, note that our needle size was automatically converted to metric. There are various options on the pattern renderer that will allow you to use the system of units most familiar to you, regardless of what the original pattern was written in. (Note that the pattern renderer does not currently support these options, but it will in a future release.)

Here is the gauge specification in metric:

Simple Square
A simple square

Stitch Gauge: 2.4 st/cm
Row Gauge: 2.4 row/cm
...

Also note that, even though we specified that the pattern is written in English, this pattern can (for the most part) be rendered in another language very easily. Simply setting the renderer to use Spanish (using pattern conventions from Spain) produces this result:

...
Instrucciones
-------------
Usando el montado doble, monta 24 puntos.
Hilera 1: Todo del derecho
Hilera 2: Todo del reves
Repite hileras 1-2 hasta que la pieza mida 4 in.
...

Note that the header information (i.e. the parts of the pattern written in English) would always be written in English unless you internationalized them. See Chapter 5, Internationalization for more information.

Our simple square pattern renders fine. There are, however, a couple of quirks that we can eliminate. The first is that there are not line breaks where you would expect them to be in a traditional pattern. You can fix this by adding section elements to break the pattern up into logical paragraphs.

Pattern 'en' {
...
    Section {
      CastOn 24 'long-tail'
    }
    Section {
      Instruction 'stockinette-st' {
        Row: k to end
        Row: p to end
      }
      Repeat 'stockinette-st' until measures 4 in
    }
    Section {
      Row: BindOff all sts
    }
  }
}

The renderer will produce:

...
Directions
----------
Using the long-tail method, cast on 24 stitches.

Row 1: Knit
Row 2: Purl
Repeat rows 1-2 for 4 in.

Row 25: Bind off all stitches

Here's another thought. A pattern designer may want to define more than one instruction group in the pattern. Think about knitting a sock, for instance. There are separate instructions for knitting the cuff, leg, heel flap, heel turn, gusset, foot, and toe. Being able to add headers to each instruction group would be very useful.

You can add instruction groups in the directions and label them.

pattern 'en' {
...
    InstructionGroup [label:'Cast On'] {
      CastOn 24 'long-tail'
    }
    InstructionGroup [label:'Make the Square'] {
      Instruction 'stockinette-st' {
        Row: k to end
        Row: p to end
      }
      Repeat 'stockinette-st' until measures 4 in
    }
    InstructionGroup [label:'Finish It Off!'] {
      Row: bindOff all sts
    }
...
}

This would look like:

Directions
----------
Cast On
-------
Using the long-tail method, cast on 24 stitches.

Make The Square
---------------
Row 1: Knit
Row 2: Purl
Repeat rows 1-2 for 4 in.

Finish It Off!
--------------
Row 25: bind off all stitches

Another quirk is that you probably would not see the bind off row expressed as Row 25. To reset the row count for this instruction group, add the keyword resetRowCount to the definition:

Pattern 'en' {
...
    InstructionGroup [label:'Finish It Off!'] resetRowCount {
      Row: BindOff all sts
    }
...
}

This will produce:

Finish It Off!
--------------
Row 1: Bind off all stitches

Alternatively, you may not want the row numbered at all, in which case you can do this:

Pattern 'en' {
...
    InstructionGroup [label:'Finish It Off!'] {
      NextRow: BindOff all sts
    }
...
}

and you will get:

...
Finish It Off!
--------------
Next Row: Bind off all stitches

The operations resource bundle used to render patterns is embedded in the knitml-pattern-renderer.jar file. For your reference, the master resource bundle file has been copied to KNITML_HOME/conf/local-operations.properties. If you open it, you will see a list of name / value pairs, each separated by an equals sign and delineated by line. Each entry constitutes a phrase in a knitting pattern, with parameters supplied to it by the renderer and referenced by {0} (for the first parameter), {1} (for the second parameter), etc. You will base any customizations you make to the renderer on this file.

As knitters are a diverse group of individuals, knitters often use different notations and conventions to express the same technique. Sometimes terms vary regionally differ, and other times the techniques vary slightly but produce the same result.

Knitting a stitch so that it is twisted is a good example of a technique which can be described using different terms. Most knitters know this technique by the term "knitting through the back loop." This term, however, assumes that the mount of the stitch being worked is not reversed. While that generally is true if you are a western knitter, it is not necessarily true if you are a combination knitter. In combination knitting, if the same stitch in the previous row had been purled, the mount of that stitch would be reversed. If that is true, the back loop would not be the loop to knit to create a twisted stitch; it would be the front loop. It is more accurate to describe the loop to knit as the "trailing" loop instead of the "back" loop^[4].

Another example is the yarn-over increase. Most commonly this is known by the abbreviation yo but can also be represented by yfon (yarn forward and over needle), yfrn (yarn forward and 'round needle), yon (yarn over needle), and yrn (yarn 'round needle).

You can instruct the renderer to use your favorite terms for knitting techniques instead of the defaults. Open the custom-operations.properties file in the KNITML_HOME/conf directory and copy over the entries you want to customize from local-operations.properties. A few samples are included in the comments (including the yarn-over customizations described above). To use one of them, simply remove the beginning # sign (which designates a comment) from the line you want to use.

Let's suppose a pattern I've rendered looks like this:

Row 1: k12, yo, k1

To make the yarn-over increase look like yrn (yarn 'round needle), I would open up custom-operations.properties and edit this line:

#operation.increase.yo=yrn

and make it look like this:

operation.increase.yo=yrn

Now my pattern would render like this:

Row 1: k12, yrn, k1

To change the way knits render, I could add this line:

operation.knit.$$$=k {0} st;k {0} sts

and it would look like this^[5]:

Row 1: k 12 sts, yrn, k 1 st

There are several more examples of personalizations in the custom-operations.properties file.