HTML templates

Every page in an HTML disassembly is built from the Layout template and zero or more subtemplates defined by [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 [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 [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 [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 [Game] section when the template is formatted.

Changed in version 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].

Changed in version 6.4: Added SkoolKit[path].

Layout

The Layout template is used to format every HTML page.

In any page defined by a [Page:*] section, the following identifier is available (in addition to the universal identifiers):

  • Page - a dictionary of the parameters in the corresponding [Page:*] section

In any page defined by a [MemoryMap:*] section, the following identifier is available (in addition to the universal identifiers):

  • MemoryMap - a dictionary of the parameters in the corresponding [MemoryMap:*] section

To see the default Layout template, run the following command:

$ skool2html.py -r Template:Layout

New in version 8.0.

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 skool2html.py)
  • anchor - the anchor for the entry, formatted according to the value of the AddressAnchor parameter in the [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 [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 skool2html.py)
  • anchor - the anchor for the instruction, formatted according to the value of the AddressAnchor parameter in the [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 [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 @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$

Changed in version 8.1: Added the fmt parameter to the format specifier for the bytes attribute of instruction objects.

New in version 8.0.

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 asm template.

To see the default asm_single_page template, run the following command:

$ skool2html.py -r Template:asm_single_page

New in version 8.0.

box_entries

The box_entries template is used to format the content between the header and footer of a 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

New in version 8.0.

box_list_entries

The box_list_entries template is used to format the content between the header and footer of a 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 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

New in version 8.0.

home

The home template is used to format the content between the header and footer of the disassembly home page.

The following identifier is available (in addition to the universal identifiers):

  • sections - a list of section objects

Each section object represents a group of links and has the following attributes:

  • header - the header text for the group of links (as defined in the name of the [Index:*:*] section)
  • items - a list of items in the group

Each item represents a link to a page and has the following attributes:

  • href - the relative path to the page being linked to
  • link_text - the link text for the page (as defined in the [Links] section)
  • other_text - the supplementary text displayed alongside the link (as defined in the [Links] section)

To see the default home template, run the following command:

$ skool2html.py -r Template:home

New in version 8.0.

img

The img template is used to format <img> elements for the image macros and for the game logo image (if defined) in the header of every page.

The following identifiers are available (in addition to the universal identifiers):

  • alt - the ‘alt’ text for the image
  • src - the relative path to the image file

To see the default img template, run the following command:

$ skool2html.py -r Template:img

item_list

The item_list template is the subtemplate used by the box_list_entries template to format a list of items (or subitems, or subsubitems etc.) in an entry on a box page whose SectionType is BulletPoints or ListItems.

The following identifiers are available (in addition to the universal identifiers):

  • indent - the indentation level of the item list: ‘’ (blank string) for the list of top-level items, ‘1’ for a list of subitems, ‘2’ for a list of subsubitems etc.
  • items - a list of item objects

Each item object has the following attributes:

  • subitems - a preformatted list of subitems (may be blank)
  • text - the text of the item

Note that the item_list template is used to format the subitems attribute of each item (this template is recursive).

To see the default item_list template, run the following command:

$ skool2html.py -r Template:item_list

New in version 8.0.

list

The list template is used by the #LIST macro to format a list.

The following identifiers are available (in addition to the universal identifiers):

  • class - the CSS class name for the list
  • items - the list items

To see the default list template, run the following command:

$ skool2html.py -r Template:list

Changed in version 8.0: Replaced the m_list_item identifier with the items identifier.

New in version 4.2.

memory_map

The memory_map template is used to format the content between the header and footer of memory map pages and the ‘Game status buffer’ page.

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 prev_entry and next_entry dictionaries in the asm template.

To see the default memory_map template, run the following command:

$ skool2html.py -r Template:memory_map

New in version 8.0.

page

The page template is used to format the content between the header and footer of a non-box page defined by a [Page:*] section.

To see the default page template, run the following command:

$ skool2html.py -r Template:page

New in version 8.0.

reg

The reg template is the subtemplate used by the #REG macro to format a register name.

The following identifier is available (in addition to the universal identifiers):

  • reg - the register name (e.g. ‘HL’)

To see the default reg template, run the following command:

$ skool2html.py -r Template:reg

section

The section template is used to format the paragraphs in a ref file section processed by the #INCLUDE macro.

The following identifier is available (in addition to the universal identifiers):

  • section - a list of paragraphs

To see the default section template, run the following command:

$ skool2html.py -r Template:section

New in version 8.0.

table

The table template is used by the #TABLE macro to format a table.

The following identifiers are available (in addition to the universal identifiers):

  • class - the CSS class name for the table
  • rows - a list of row objects

Each row object has a cells attribute, which is a list of cell objects for that row. Each cell object has the following attributes:

  • class - the CSS class name for the cell
  • colspan - the number of columns spanned by the cell
  • contents - the contents of the cell
  • header - 1 if the cell is a header cell, 0 otherwise
  • rowspan - the number of rows spanned by the cell

To see the default table template, run the following command:

$ skool2html.py -r Template:table

Changed in version 8.0: Replaced the m_table_row identifier with the rows identifier.

New in version 4.2.

Template directives

HTML templates may contain directives enclosed by <# and #> to conditionally include or repeat content. To take effect, a directive must appear on a line of its own.

foreach

The foreach directive repeats the content between it and the corresponding endfor directive, once for each object in a list.

<# foreach(var,list) #>
content
<# endfor #>
  • var is the loop variable, representing each object in the list
  • list is the list of objects to iterate over

Wherever the string var appears in content, it is replaced by list[0], list[1], etc. Care should be taken to name the loop variable such that no unwanted replacements are made.

For example, if names contains the strings ‘Alice’, ‘Bob’ and ‘Carol’, then:

<# foreach(name,names) #>
{name}
<# endfor #>

would produce the following output:

Alice
Bob
Carol

if

The if directive includes the content between it and the corresponding else directive (optional) or endif directive (required) if a given expression is true, and excludes it otherwise.

<# if(expr) #>
content
<# else #>
alternative content
<# endif #>

expr may be any syntactically valid Python expression, and may contain the names of any fields that are available in the template.

The if directive follows the same rules as Python when determining the truth of an expression: None, False, zero, and any empty string or collection is false; everything else is true.

Note that any replacement fields in expr are replaced with their string representations before the expression is evaluated. For example, if the value of the field ‘val’ is the string ‘0’, then val evaluates to ‘0’ (which is true, because it’s a non-empty string); but {val} evaluates to 0 (which is false).

include

The include directive includes content from another template.

<# include(template) #>

template is the name of the template to include; it may contain replacement fields.

For example, if there is a template named title that contains <title>{title}</title>, and the title field holds the string ‘My Page’, then:

<head>
<# include(title) #>
</head>

would produce the following output:

<head>
<title>My Page</title>
</head>

Page-specific templates

When SkoolKit builds an HTML page, it uses the template whose name matches the page ID (PageID) if it exists, or the stock Layout template otherwise. For example, when building the RoutinesMap memory map page, SkoolKit will use the RoutinesMap template if it exists.

Wherever Asm-* appears in the tables below, it means one of Asm-b, Asm-c, Asm-g, Asm-s, Asm-t, Asm-u or Asm-w, depending on the type of memory map entry.

Page type Preferred template(s)
Home (index) GameIndex
Other code index CodeID-Index
Routine/data block Asm-*, Asm
Other code routine/data block CodeID-Asm-*, CodeID-Asm
Disassembly (single page) AsmSinglePage
Other code disassembly (single page) CodeID-AsmSinglePage
Memory map PageID
Box page PageID
Custom page (non-box) PageID

When SkoolKit builds the content of an HTML page between the page header and footer, it uses the subtemplate whose name starts with PageID- if it exists, or the appropriate stock subtemplate otherwise. For example, when building the entries on the Changelog page, SkoolKit uses the Changelog-box_list_entries template if it exists, or the stock box_list_entries template otherwise.

Page type Preferred template(s) Stock template
Routine/data block Asm-*-asm, Asm-asm asm
Other code routine/data block CodeID-Asm-*-asm, CodeID-Asm-asm asm
Disassembly (single page) AsmSinglePage-asm_single_page asm_single_page
Other code disassembly (single page) CodeID-AsmSinglePage-asm_single_page asm_single_page
Box page with regular entries PageID-box_entries box_entries
Box page with list entries PageID-box_list_entries box_list_entries
Home (index) GameIndex-home home
Memory map PageID-memory_map memory_map
Other code index CodeID-Index-memory_map memory_map
Custom page (non-box) PageID-page page

When SkoolKit builds an element of an HTML page whose format is defined by a subtemplate, it uses the subtemplate whose name starts with PageID- if it exists, or one of the stock subtemplates otherwise. For example, when building the footer of the Changelog page, SkoolKit uses the Changelog-footer template if it exists, or the stock footer template otherwise.

Element type Preferred template Stock template
Page footer PageID-footer footer
<img> element PageID-img img
Box page list entry PageID-item_list item_list
Hyperlink PageID-link link
List created by the #LIST macro PageID-list list
Register name rendered by the #REG macro PageID-reg reg
Table created by the #TABLE macro PageID-table table