First, I created a project named Banff.
;)
;)
Then I created the KEL file...
;)
...renaming the default file name to banff.kel.
;)
Here is what I started with. This is a template that highlights the basic structure of the document.
;)
A KnitML pattern consists of exactly one Pattern element. The Pattern element itself has a GeneralInformation, a Supplies, and a Directions element, and those in turn have elements. If an element cannot be defined all on one line, its contents are indicated by curly braces.
Then I took a look at the original pattern and put that information manually into this document. Since the pattern is given in two sizes, I picked the S-M size to convert.
;)
Elements like Name, Description, and Dimensions were fairly self-explanatory. I converted the square gauge (14 sts x 21 rows = 4 in) into decimal form (3.5 stitchesPerInch, 5.25 rowsPerInch). Knitters who like to read square gauge have an option to create their pattern that way, so I didn't need to worry about that.
For sake of clarity and convention, items surrounded by double quotes are different from items with single quotes. Double quotes refer to literal text or a label. That is, they are written in a particular language (English in this case, as specified by the "en" value by the Pattern element). The values for Name and Description, for instance, are surrounded by double quotes.
Single quotes refer to system IDs. These IDs provide a way to refer to the element upon where they appear in a different part of the pattern. It's a good idea to make them readable, but they don't have to be (they could be generated, for instance). IDs have a few restrictions. They must be unique in the pattern, and they cannot start with a number or cannot contain spaces. (They follow the NCName rules for XML IDs, if that means anything to you.) Additionally, an element cannot refer to an ID that is defined later in the document (elements are processed from the start of the file to the end). That is why they appear with dashes where spaces would normally be ('yarn-type1' or 'needle1', not 'yarn type 1' or '1st-needle').
The original pattern has a section called Patterns. It defines three sets of instructions for use in the pattern directions. The 2x2 Rib pattern is a two-row instruction. RS Decrease Row and WS Decrease Row never appear apart, so I consolidated them into an instruction called Decrease Rows. Also, since the pattern needs to refer to Stockinette Stitch, I included that definition as well. To make these three instructions appear in the header, they went into the Directives and InstructionDefinitions elements, which appears directly under the Pattern element.
;)
Notice that Row elements do not have to have row numbers; they are optional. When they appear in the header like this, if they are not provided, it is assumed that each instruction starts with row 1. (When they are in the body, row numbers will start with row 1 and continue upwards until they are reset.) Additionally, instructions in the header must specify how they are to be worked: flat or round.
Next come the directions themselves. The original pattern is organized into major sections: Back, Right Shoulder, Left Shoulder, Front, Left Shoulder, Right Shoulder, Sleeves (2), and Finishing. In KnitML, each of these sections correspond to an InstructionGroup element. Each InstructionGroup gets an ID (to refer to) and a label (to display).
An InstructionGroup element can be made up of Section elements. Each Section element corresponds to a paragraph in the original pattern. I did my best to make these correspond to the way the pattern was organized.
Here is the InstructionGroup for the back:
;)
I consolidated a few things in this InstructionGroup. The original pattern has the 2x2 ribbing repeat listed as a 42-row repeat. To me, it seemed like the designer meant the ribbing to be repeated for 8 inches, since the row gauge was specified at 21 rows to the inch. I chose to express it by length because it seemed a bit more natural (and possibly more accurate in case a knitter was not getting the exact row gauge). I interpreted increasing 4 stitches "more or less evenly" across 86 stitches to mean k21, m1, k22, m1, k21, m1, k22, m1. (In the future, there may be a way to express an even increase like this, but right now the designer has to be explicit.)
An InformationalMessage element provides a way for the designer to add helpful advice to the pattern. This can be anything from a detailed explanation of a technique to informal suggestions about altering the pattern. Additionally, there will be a way for an InformationalMessage to provide a "summary" explanation of more detailed knitting. In this case, the designer will provide the summary and then the details of the technique, and the knitter can choose to "fold up" the details if they don't want to see them (or the pattern can start "folded up" if they prefer it that way).
Notice how some parts of the pattern have a "State sts" element, while others say "State 34 sts." I did this mostly to show both ways of doing this. "State sts" will simply state the number of stitches currently being worked (whatever that number is). "State 34 sts" will do the same, but it will ensure that there are 34 stitches being worked and throw an error if it's not. This can help identify copy and paste errors.
The next section is the back right shoulder.
;)
This section highlighted some deficiencies in the current KnitML specification. For instance, there is not yet a way to express putting stitches on a holder in KnitML. (This will change in an upcoming version of the specification.) As a result, there is an abnormal bind off / cast on combination in this InstructionGroup that doesn't quite follow the original pattern. Please forgive this section for now. :)
I then went on to transcribe the Left Shoulder (Back), Front, Left Shoulder (Front), Right Shoulder, and Sleeves. The Sleeves required a level of detail which was merely summarized in the original pattern. Since KnitML needs to know exactly how to work the stitches, I had to derive the details based on the general instruction. (This will be implemented as a foldable instruction in the future.)
Here is how I generally approached transcribing each row from the original pattern. I started out copying each row from the web site and pasting in into the KEL file. Then I did some minimal altering to make it fit into the KEL format. For example, the original pattern had a purl 1 through back loop expressed as 'p1tbl.' In KEL this is actually 'p1 tbl' (with a space). [RS] / [WS] also look like 'rightSide' and 'wrongSide' instead. Also, the desinger used spaces to delineate her row labels, whereas KEL expects colons. (At some point, some of this expected formatting may be able to be customized by the designer. We're not there yet, though.)
Each row takes the form of:
Row [number(s)] ("rightSide" | "wrongSide"): operation(s) or Row [number(s)] ("rightSide" | "wrongSide") {
operation
operation
}For instance:Row 1: k to endIf you don't want the row number to appear, use the NextRow element instead. If you have a short row, use ShortRow.
Row 2 wrongSide: p to end
Row [3,5,7]: k to 2 before end, p2
Row [4,6,8] wrongSide {
p to 2 before end
k2
}
If you specify multiple row numbers that are not sequential (such as Row [4,6,8] above), you must surround the complete set of rows with an Instruction element. So the above rows would actually look like this:
Instruction 'inst1' {
Row 1: k to end
Row 2 wrongSide: p to end
Row [3,5,7]: k to 2 before end, p2
Row [4,6,8] wrongSide {
p to 2 before end
k2
}
}The last InstructionGroup was the finishing instructions. The KnitML Specification currently doesn't have a good way to express picking up along an edge, so this section is done as InformationalMessages surrounded by Sections. Defining edges will be in a future spec.That is how I created the pattern. In the next post, I'll show you what I'm able to do with the pattern once it's in this format.
[ add comment ] ( 3 views ) | [ 0 trackbacks ] | permalink
Archives
