.. _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`` - an object representing the current memory map entry (see below) * ``next_entry`` - an object representing the next memory map entry (see below) * ``prev_entry`` - an object representing the previous memory map entry (see below) The attributes in the ``prev_entry`` and ``next_entry`` objects 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 * ``length`` - the size of the entry in bytes, as a string formatted according to the value of the ``Length`` parameter in the :ref:`ref-game` section * ``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`` object also has these attributes, 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. The format specifier for this attribute has the following form:: bfmt or:: /bfmt/sep[/fmt] * ``bfmt`` is the format specifier applied to each byte value * ``sep`` is the separator string inserted between byte values; by default it is blank * ``fmt`` is the format specifier applied to the entire string of byte values; by default it is blank The delimiter used here (``/``) to separate the ``bfmt``, ``sep`` and ``fmt`` parameters is arbitrary; it could be any character that doesn't appear in ``bfmt`` itself. For example:: {$instruction[bytes]:02X} would produce the string ``3E01`` for the instruction 'LD A,1'. And:: {$instruction[bytes]:/02X/ />11} would render byte values as 2-digit upper case hexadecimal numbers separated by spaces, and right align the entire field to a width of 11 characters. 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 specifier is blank, the ``bytes`` identifier produces an empty string. To see the default ``asm`` template, run the following command:: $ skool2html.py -r Template:asm$ .. versionchanged:: 8.4 Added the ``length`` attribute to entry objects. .. versionchanged:: 8.1 Added the ``fmt`` parameter to the format specifier for the ``bytes`` attribute of instruction objects. .. 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 of the ``entry`` object 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_audio: audio ----- The ``audio`` template is used to format ``