.. _htmlTemplates:
HTML templates
==============
Every page in an HTML disassembly is built from the :ref:`t_Layout` template
and zero or more subtemplates defined by :ref:`template` sections in the ref
file.
A template may contain 'replacement fields' - identifiers enclosed by braces
(``{`` and ``}``) - that are replaced by appropriate content (typically derived
from the skool file or a ref file section) when the template is formatted. The
following 'universal' identifiers are available in every template:
* ``Game`` - a dictionary of the parameters in the :ref:`ref-game` section
* ``SkoolKit`` - a dictionary of parameters relevant to the page currently
being built
The parameters in the ``SkoolKit`` dictionary are:
* ``include`` - the name of the subtemplate used to format the content between
the page header and footer
* ``index_href`` - the relative path to the disassembly index page
* ``javascripts`` - a list of javascript objects; each one has a single
attribute, ``src``, which holds the relative path to the JavaScript file
* ``page_header`` - a two-element list containing the page header prefix and
suffix (as defined in the :ref:`pageHeaders` section)
* ``page_id`` - the page ID (e.g. ``GameIndex``, ``MemoryMap``)
* ``path`` - the page's filename, including the full path relative to the root
of the disassembly
* ``stylesheets`` - a list of stylesheet objects; each one has a single
attribute, ``href``, which holds the relative path to the CSS file
* ``title`` - the title of the page (as defined in the :ref:`titles` section)
The parameters in a dictionary are accessed using the ``[param]`` notation;
for example, wherever ``{Game[Copyright]}`` appears in a template, it is
replaced by the value of the ``Copyright`` parameter in the :ref:`ref-game`
section when the template is formatted.
.. versionchanged:: 8.0
``SkoolKit[page_header]`` is a two-element list containing the page header
prefix and suffix. Added ``SkoolKit[include]``, ``SkoolKit[javascripts]``
and ``SkoolKit[stylesheets]``.
.. versionchanged:: 6.4
Added ``SkoolKit[path]``.
.. _t_Layout:
Layout
------
The ``Layout`` template is used to format every HTML page.
In any page defined by a :ref:`page` section, the following identifier is
available (in addition to the universal identifiers):
* ``Page`` - a dictionary of the parameters in the corresponding :ref:`page`
section
In any page defined by a :ref:`memoryMap` section, the following identifier is
available (in addition to the universal identifiers):
* ``MemoryMap`` - a dictionary of the parameters in the corresponding
:ref:`memoryMap` section
To see the default ``Layout`` template, run the following command::
$ skool2html.py -r Template:Layout
.. versionadded:: 8.0
.. _t_asm:
asm
---
The ``asm`` template is used to format the content between the header and
footer of a disassembly page.
The following identifiers are available (in addition to the universal
identifiers):
* ``entry`` - a dictionary of parameters corresponding to the current memory
map entry (see below)
* ``next_entry`` - a dictionary of parameters corresponding to the next memory
map entry (see below)
* ``prev_entry`` - a dictionary of parameters corresponding to the previous
memory map entry (see below)
The parameters in the ``prev_entry`` and ``next_entry`` dictionaries are:
* ``address`` - the address of the entry (may be in decimal or hexadecimal
format, depending on how it appears in the skool file, and the options passed
to :ref:`skool2html.py`)
* ``anchor`` - the anchor for the entry, formatted according to the value of
the ``AddressAnchor`` parameter in the :ref:`ref-game` section
* ``byte`` - the LSB of the entry address
* ``description`` - a list of paragraphs comprising the entry description
* ``exists`` - '1' if the entry exists, '0' otherwise
* ``href`` - the relative path to the disassembly page for the entry
* ``label`` - the ASM label of the first instruction in the entry
* ``location`` - the address of the entry as a decimal number
* ``map_href`` - the relative path to the entry on the 'Memory Map' page
* ``page`` - the MSB of the entry address
* ``size`` - the size of the entry in bytes
* ``title`` - the title of the entry
* ``type`` - the block type of the entry ('b', 'c', 'g', 's', 't', 'u' or 'w')
The ``entry`` dictionary also contains these parameters, and the following
additional ones:
* ``annotated`` - '1' if any instructions in the entry have a non-empty comment
field, '0' otherwise
* ``end_comment`` - a list of paragraphs comprising the entry's end comment
* ``input_registers`` - a list of input register objects
* ``instructions`` - a list of instruction objects
* ``labels`` - '1' if any instructions in the entry have an ASM label, '0'
otherwise
* ``output_registers`` - a list of output register objects
* ``show_bytes`` - '1' if the entry contains at least one assembled instruction
with byte values and the ``Bytes`` parameter in the :ref:`ref-Game` section
is not blank, '0' otherwise
Each input and output register object has the following attributes:
* ``description`` - the register's description (as it appears in the register
section for the entry in the skool file)
* ``name`` - the register's name (e.g. 'HL')
Each instruction object has the following attributes:
* ``address`` - the address of the instruction (may be in decimal or
hexadecimal format, depending on how it appears in the skool file, and the
options passed to :ref:`skool2html.py`)
* ``anchor`` - the anchor for the instruction, formatted according to the value
of the ``AddressAnchor`` parameter in the :ref:`ref-game` section
* ``block_comment`` - a list of paragraphs comprising the instruction's
mid-block comment
* ``bytes`` - the byte values of the assembled instruction (see below)
* ``called`` - '2' if the instruction is an entry point, '1' otherwise
* ``comment`` - the text of the instruction's comment field
* ``comment_rowspan`` - the number of instructions to which the comment field
applies; this will be '0' if the instruction has no comment field
* ``label`` - the instruction's ASM label
* ``location`` - the address of the instruction as a decimal number
* ``operation`` - the assembly language operation (e.g. 'LD A,B'), with operand
hyperlinked if appropriate
The ``bytes`` attribute can be used to render the byte values of an
instruction. In its simplest form, it provides a format specification that is
applied to each byte. For example::
{$instruction[bytes]:02X}
would produce the string ``3E01`` for the instruction 'LD A,1'.
To render the byte values as 0-padded decimal integers separated by commas, use
the following syntax::
{$instruction[bytes]:/03/,}
This would produce the string ``062,001`` for the instruction 'LD A,1'. The
delimiter used in this example (``/``) is arbitrary; it could be any character
that doesn't appear in the byte format specification itself.
By default, the ``Bytes`` parameter in the :ref:`ref-Game` section is used as
the byte format specification::
{$instruction[bytes]:{Game[Bytes]}}
If you define a custom template that replaces ``{Game[Bytes]}`` with a
hard-coded byte format specification, it's a good idea to also remove the
``if({entry[show_bytes]})`` directive (and the corresponding ``endif``), to
ensure that the byte values are displayed.
Note that byte values are available only for regular assembly language
instructions (not DEFB, DEFM, DEFS or DEFW statements), and only if they have
actually been assembled by using :ref:`@assemble=2 `. When no byte
values are available, or the format specification is blank, the ``bytes``
identifier produces an empty string.
To see the default ``asm`` template, run the following command::
$ skool2html.py -r Template:asm$
.. versionadded:: 8.0
.. _t_asm_single_page:
asm_single_page
---------------
The ``asm_single_page`` template is used to format the content between the
header and footer of a single-page disassembly.
The following identifier is available (in addition to the universal
identifiers):
* ``entries`` - a list of memory map entry objects
The attributes of each memory map entry object are the same as those in the
``entry`` dictionary in the :ref:`t_asm` template.
To see the default ``asm_single_page`` template, run the following command::
$ skool2html.py -r Template:asm_single_page
.. versionadded:: 8.0
.. _t_box_entries:
box_entries
-----------
The ``box_entries`` template is used to format the content between the header
and footer of a :ref:`box page ` with a default ``SectionType``.
The following identifier is available (in addition to the universal
identifiers):
* ``entries`` - a list of entry objects
Each entry object has the following attributes:
* ``anchor`` - the anchor for the entry
* ``contents`` - a list of paragraphs comprising the contents of the entry
* ``order`` - '1' or '2', depending on the order of the entry on the page
* ``title`` - the entry title
To see the default ``box_entries`` template, run the following command::
$ skool2html.py -r Template:box_entries
.. versionadded:: 8.0
.. _t_box_list_entries:
box_list_entries
----------------
The ``box_list_entries`` template is used to format the content between the
header and footer of a :ref:`box page ` whose ``SectionType`` is
``BulletPoints`` or ``ListItems``.
The following identifier is available (in addition to the universal
identifiers):
* ``entries`` - a list of entry objects
Each entry object has the following attributes:
* ``anchor`` - the anchor for the entry
* ``intro`` - the entry intro text
* ``item_list`` - replaced by a copy of the :ref:`t_item_list` subtemplate
* ``order`` - '1' or '2', depending on the order of the entry on the page
* ``title`` - the entry title
To see the default ``box_list_entries`` template, run the following command::
$ skool2html.py -r Template:box_list_entries
.. versionadded:: 8.0
.. _t_footer:
footer
------
The ``footer`` template is the subtemplate included in the :ref:`t_Layout`
template to format the ``