.. _migrating:

Migrating from SkoolKit 4
=========================
SkoolKit 5 includes some changes that make it incompatible with SkoolKit 4. If
you have developed a disassembly using SkoolKit 4 and find that the SkoolKit
commands no longer work with your control files or skool files, or produce
broken output, look through the following sections for tips on how to migrate
your disassembly to SkoolKit 5.

D directives
------------
In SkoolKit 4, the ``D`` directive in a control file could be used to define a
block description or a mid-block comment. In SkoolKit 5, the ``D`` directive
defines block descriptions only; to define a mid-block comment, use the ``N``
directive instead.

Address ranges in control directives
------------------------------------
In SkoolKit 4, the extent of a sub-block directive in a control file could be
specified by an address range; for example::

  B 40000-40009

In SkoolKit 5, address ranges are no longer supported, and this directive must
be rewritten with a length parameter::

  B 40000,10

ASM directives
--------------
In SkoolKit 4, ASM directives could be declared in a control file or a skool
file by starting a line with ``; @``; for example, in a control file::

  ; @label:24576=START

and in a skool file (or skool file template)::

  ; @label=START

This syntax is no longer supported. In SkoolKit 5, ASM directives must be
declared in a control file by using the ``@`` directive::

  @ 24576 label=START

and in a skool file (or skool file template) by starting a line with ``@``::

  @label=START

HTML templates and CSS
----------------------
If you are using any custom :ref:`htmlTemplates` - in particular the full-page
templates or the :ref:`t_anchor` template - or custom CSS, there are some
changes to be aware of.

In SkoolKit 4:

* the default full-page templates use the XHTML 1.0 Strict DOCTYPE
* every full-page template contains its own copy of the page footer
* the ``anchor`` template uses an ``<a>`` element with a ``name`` attribute
* every ``<a>`` element that defines a hyperlink has a ``class="link"``
  attribute

In SkoolKit 5:

* the default full-page templates have been converted to HTML5
* every full-page template uses the :ref:`t_footer` template to format the page
  footer
* the ``anchor`` template uses a ``<span>`` element with an ``id`` attribute
* the ``class="link"`` attribute has been removed from every ``<a>`` element
  that defines a hyperlink

This means that if you are using any custom full-page templates or a custom
``anchor`` template, you should ensure that they are consistent (i.e. produce
valid HTML5 or XHTML 1.0 as required when used in combination).

In addition, if you are using any custom full-page templates, you should either
replace the page footer (the ``<div class="footer">`` element) with a
``{t_footer}`` replacement field, or reinstate the CSS rule for ``div.footer``
from SkoolKit 4::

  div.footer {
    clear: both;
    margin-top: 10px;
    text-align: center;
  }

And finally, if you have defined any custom CSS rules for hyperlinks, you
should remove the 'link' class from the selectors. For example, this CSS rule
from `skoolkit.css` in SkoolKit 4::

  a.link { color: #ffff00; }

has become this in SkoolKit 5::

  a { color: #ffff00; }

skool2asm.py
------------
In SkoolKit 4 and earlier versions, :ref:`skool2asm.py` sported the
``-d/--crlf`` option (to use CR+LF to end lines instead of the system default),
the ``-i/--inst-width`` option (to set the width of the instruction field), and
the ``-t/--tabs`` option (to use tab to indent instructions). These options
have been removed in SkoolKit 5, but their effects can be achieved with the
new ``-P/--set`` option:

+--------------------+-------------------------------+
| SkoolKit 4         | SkoolKit 5                    |
+====================+===============================+
| ``--crlf``         | ``--set crlf=1``              |
+--------------------+-------------------------------+
| ``--inst-width N`` | ``--set instruction-width=N`` |
+--------------------+-------------------------------+
| ``--tabs``         | ``--set tab=1``               |
+--------------------+-------------------------------+

skoolkit4to5.py
---------------
The `skoolkit4to5.py`_ script may be used to convert a control file, skool
file, skool file template or CSS file that is compatible with SkoolKit 4 into a
file that will work with SkoolKit 5. For example, to convert `game.skool`::

  $ skoolkit4to5.py game.skool > game5.skool

.. _skoolkit4to5.py: https://github.com/skoolkid/skoolkit/raw/master/utils/skoolkit4to5.py