Manual/File format

The native file format for Knotter is a human-readable XML.

Knot file v4

Follows a commented example file to show the XML elements and attributes

<?xml version="1.0" encoding="UTF-8"?>
<!-- 
  <knot>     Root element
  version    Knot document version, see below
  generator  String displaying the version of Knotter used to generate the file
-->
<knot version="4" generator="Knotter 0.9.5">
    <style>                                     <!-- Contains information about the display and style of the knot -->
        <colors>                                <!-- List of colors -->
            <color alpha="255">#99ff00</color>  <!-- The text must be a valid SVG color (hex notation or name) -->
            <color alpha="255">#ff9700</color>  <!-- Alpha is the transparency, ranged from 0 to 255 -->
        </colors>
        <borders>                                           <!-- List of borders -->
            <border width="3" alpha="255">#000000</border>  <!-- Same element as color, but with the width attribute-->
            <border width="3" alpha="255">#ffffff</border>
            <border width="1" alpha="255">#000000</border>
        </borders>
        <cusp>                                  <!-- Default cusp style -->
            <shape>pointed</shape>              <!-- Shape of the cusp -->
            <min-angle>225</min-angle>          <!-- Minimum angle (in degrees) to trigger a cusp redering -->
            <distance>32</distance>             <!-- Distance from cusp and node -->
        </cusp>
        <crossing>                              <!-- Default crossing style -->
            <gap>10</gap>                       <!-- Crossing gap -->
            <slide>0.5</slide>                  <!-- Crossing offset -->
            <handle-length>24</handle-length>   <!-- Curve control -->
        </crossing>
        <stroke>
            <width>5</width>                    <!-- Width of the ropes -->
            <style>SolidPattern</style>         <!-- Brush style, ignored as of 0.9.0 -->
            <join>MiterJoin</join>              <!-- Joint style -->
        </stroke>
    </style>
    <graph>                                     <!-- Graph structure -->
        <nodes>                                 <!-- List of all the nodes -->
            <node id="node_1" x="-128" y="-160"/><!-- A node in the graph -->
            <node id="node_2" x="-128" y="-96"/> <!-- id must be a valid XML ID, referenced by the edges -->
            <node id="node_3" x="-64" y="-96"/>  <!-- x,y are the position of the node -->
            <node id="node_4" x="-64" y="-160"/>
            <node id="node_5" x="0" y="-32">
                <style>                          <!-- Override default node style -->
                    <shape>round</shape>         <!-- Can contain anything that is in /knot/style/cusp -->
                    <distance>40</distance>      <!-- But all the elements are optional -->
                </style>                         <!-- The value of such elements override the default node style -->
            </node>
            <node id="node_6" x="-32" y="0">
                <style>
                    <shape>round</shape>
                    <distance>40</distance>
                </style>
            </node>
            <node id="node_7" x="0" y="32">
                <style>
                    <shape>round</shape>
                    <distance>40</distance>
                </style>
            </node>
            <node id="node_8" x="32" y="0">
                <style>
                    <shape>round</shape>
                    <distance>40</distance>
                </style>
            </node>
        </nodes>
        <edges>
        <edges>                                             <!-- list of edges -->
            <edge style="wall" v1="node_1" v2="node_2"/>    <!-- An edge connecting two nodes -->
            <edge style="regular" v1="node_2" v2="node_3"/> <!-- style is the type of edge -->
            <edge style="hole" v1="node_3" v2="node_4"/>    <!-- v1 and v2 are the IDs of the vertices -->
            <edge type="inverted" v1="node_4" v2="node_1"/>
            <edge type="regular" v1="node_5" v2="node_6">
                <style>                                     <!-- Override default node style -->
                    <gap>5</gap>                            <!-- Can contain anything that is in /knot/style/crossing -->
                    <handle-length>4</handle-length>        <!-- But all the elements are optional -->
                </style>                                    <!-- The value of such elements override the default edge style -->
            </edge>
            <edge type="regular" v1="node_6" v2="node_7"/>
            <edge type="regular" v1="node_7" v2="node_8"/>
            <edge type="regular" v1="node_8" v2="node_5"/>
        </edges>
    </graph>
</knot>

Knot file versions

1. The first version from 0.1 to 0.4.
2. The version from 0.5 to 0.8, it's mostly compatible with version 1 with only minor changes to how style is handled.
3. From 0.9.0 to 0.9.5 incompatible with previous versions.
4. Current version, it's mostly compatible with version 3 with only minor changes to how style is handled.

Knotter 0.9.5 and above writes only knot files version 4 but is able to read older versions for compatibility.