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 - 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 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
length - the size of the entry in bytes, as a string formatted according to the value of the Length parameter in the [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 [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.4: Added the length attribute to entry objects.

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 of the entry object 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.

audio¶

The audio template is used to format <audio> elements created by the #AUDIO macro.

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

src - the relative path to the audio file

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

$ skool2html.py -r Template:audio

New in version 8.7.

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.

link¶

The link template is the subtemplate used to format the hyperlinks created by the #LINK and #R macros, and the hyperlinks in instruction operands on disassembly pages.

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

href - the relative path to the page being linked to
link_text - the link text for the page

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

$ skool2html.py -r Template:link

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 of the prev_entry and next_entry objects 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
`<audio>` element	`PageID-audio`	audio
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

HTML templates¶

Layout¶

asm¶

asm_single_page¶

audio¶

box_entries¶

box_list_entries¶

footer¶

home¶

img¶

item_list¶

link¶

list¶

memory_map¶

page¶

reg¶

section¶

table¶

Template directives¶

foreach¶

if¶

include¶

Page-specific templates¶

Table of Contents

Previous topic

Next topic

This Page