whether or not to include waste yarn in example files

[gabrielle-ohlson]

I am back and forth on whether or not we should include a waste yarn section in all of the [test-files]... thoughts?

reasons to do it:

• Since the waste yarn section is what engages the rollers, running a file without it could cause problems on the machine (the file won't be knitted properly, and then also clumps, broken needles, etc)
• Although we could add a disclaimer that it is just an example file and needs additional sections before running it on the machine, I'm concerned some folks will miss that and just go ahead and load the output.kc file to test it out.

reasons not to do it:

• The waste yarn section is long and clogs up/distracts from the actual thing being demoed in the example file. It's obviously not ideal for demonstration purposes.

potential solutions:

• We could add a warning to the backend if no waste yarn section is detected (i.e. if an xfer appears before at least x number of rows have been knitted [and at the beginning, must be knitting on alternating needles]), or just a big red warning in the messages section: WARNING: it is highly recommended that a waste yarn section is included at the beginning of the piece
• We could also have a check box or prompt to ask users whether they'd like to add a waste yarn section to their piece (since that would be easy enough to prepend to the file; either detecting how many needles are in the first actual pass + a standard # of rows or prompting for needle/row count parameters)
• The most important part of the waste yarn section is the first few lines of kcode that just bring in each yarn that will be used in the piece with ~2-4 passes on alternating needles, so maybe we just always include that in example files as the 'cast-on' and then a comment like ;insert waste yarn section here

[ixchow]

Proposed fix:
in test-files, have three files for each example:

• example.js is javascript that, when run, produces example.k. One can write the waste yarn rows compactly in javascript with a for loop.
• example.k is the output of example.js and is included in the repository so that folks without a command-line javascript interpreter doesn't need to run the example.js file.
• example.kc is the output of example.k run through the backend.

[gabrielle-ohlson]

I think that sounds like a good fix.

Only issue is for the files that would be difficult to re-write as javascript (i.e. the colorwork ones); but I guess we can just omit the example.js files for those particular cases.

[ixchow]

We might also want to differentiate "test files" (used to check that the backend code is still operating correctly when features are added/changed; might not be knittable; generally short and check specific cases) from "example files" (things you might read and learn from as a new user, or possibly want to knit to test your machine).

Perhaps:

• move examples from test-files/ -> examples/
• move tests (maybe that's just small-square.k?) to tests/ (or possibly examples/tests?)
• remove test-files/

Also, consider adding a README.md or NOTES.md to both examples/ and tests/ briefly describing all of the included examples and test cases.

[ixchow]

Added a tests/ directory in 5f7b1c2 .