If you want to configure or augment an HTML disassembly, you will need one or more ref files. A ref file can be used to (for example):
A ref file must be formatted into sections separated by section names inside square brackets, like this:
[SectionName]
The contents of each section that may be found in a ref file are described below.
Each Bug:*:* section defines an entry on the ‘Bugs’ page. The section names and contents take the form:
[Bug:anchor:title]
First paragraph.
Second paragraph.
...
where:
To ensure that an entry can be linked to by the #BUG macro, the anchor name must be limited to the characters ‘$’, ‘#’, 0-9, A-Z and a-z.
Paragraphs must be separated by blank lines, and may contain HTML markup and skool macros.
Each Changelog:* section defines an entry on the ‘Changelog’ page. The section names and contents take the form:
[Changelog:title]
Intro text.
First top-level item.
First subitem.
Second subitem.
First subsubitem.
Second top-level item.
...
where title is the title of the entry, and the intro text and top-level items are separated by blank lines. Lower-level items are created by using indentation, as shown.
If the intro text is a single hyphen (-), it will not be included in the final HTML rendering.
The intro text and changelog items may contain HTML markup and skool macros.
| Version | Changes |
|---|---|
| 2.2.5 | New |
The Colours section contains colour definitions that will be used when creating images. Each line has the form:
name=R,G,B
or:
name=#RGB
where:
Recognised colour names and their default RGB values are:
| Version | Changes |
|---|---|
| 3.4 | Added support for hexadecimal RGB triplets |
| 2.0.5 | New |
The Config section contains configuration parameters in the format:
name=value
Recognised parameters are:
For information on how to create your own Python class for writing an HTML disassembly, see the documentation on extending SkoolKit.
| Version | Changes |
|---|---|
| 5.0 | Added the RefFiles parameter |
| 3.3.1 | Added support to the HtmlWriterClass parameter for specifying a module outside the module search path |
| 2.2.3 | Added the HtmlWriterClass parameter |
| 2.0 | New |
Each Fact:*:* section defines an entry on the ‘Trivia’ page. The section names and contents take the form:
[Fact:anchor:title]
First paragraph.
Second paragraph.
...
where:
To ensure that an entry can be linked to by the #FACT macro, the anchor name must be limited to the characters ‘$’, ‘#’, 0-9, A-Z and a-z.
Paragraphs must be separated by blank lines, and may contain HTML markup and skool macros.
The Game section contains configuration parameters that control certain aspects of the HTML output. The parameters are in the format:
name=value
Recognised parameters are:
The AddressAnchor parameter contains a standard Python format string that specifies the format of the anchors attached to instructions on disassembly pages and entries on memory map pages. The default format string is {address}, which produces decimal addresses (e.g. #65280); to produce 4-digit, lower case hexadecimal addresses instead (e.g. #ff00), change AddressAnchor to {address:04x}.
Note that an address anchor that starts with an upper case letter (e.g. #FF00) will be interpreted as a skool macro, and so any format string that could produce such an anchor should be avoided.
| Version | Changes |
|---|---|
| 4.3 | Added the AddressAnchor parameter |
| 4.1 | Added the LinkInternalOperands parameter |
| 4.0 | Set default values for the InputRegisterTableHeader and OutputRegisterTableHeader parameters; added the Copyright, Created and Release parameters (which used to live in the [Info] section in SkoolKit 3) |
| 3.7 | Added the JavaScript parameter |
| 3.5 | Added the Font, LogoImage and StyleSheet parameters (all of which used to live in the [Paths] section, LogoImage by the name Logo) |
| 3.4 | Added the LinkOperands parameter |
| 3.1.2 | Added the InputRegisterTableHeader and OutputRegisterTableHeader parameters |
| 2.0.5 | Added the Logo parameter |
| 2.0.3 | Added the GameStatusBufferIncludes parameter |
Each Glossary:* section defines an entry on the ‘Glossary’ page. The section names and contents take the form:
[Glossary:term]
First paragraph.
Second paragraph.
...
where term is the term being defined in the entry.
Paragraphs must be separated by blank lines, and may contain HTML markup and skool macros.
| Version | Changes |
|---|---|
| 3.1.3 | Added support for multiple paragraphs |
Each GraphicGlitch:*:* section defines an entry on the ‘Graphic glitches’ page. The section names and contents take the form:
[GraphicGlitch:anchor:title]
First paragraph.
Second paragraph.
...
where:
Paragraphs must be separated by blank lines, and may contain HTML markup and skool macros.
The ImageWriter section contains configuration parameters that control SkoolKit’s image creation library. The parameters are in the format:
name=value
Recognised parameters are:
The image-creating skool macros will create a file in the default image format if the filename is unspecified, or its suffix is omitted, or its suffix is neither .png nor .gif. For example, if DefaultFormat is png, then:
#FONT32768,26
will create an image file named font.png. To create a GIF instead (regardless of the default image format):
#FONT32768,26(font.gif)
For images that contain flashing cells, animated GIFs are recommended over animated PNGs in APNG format, because they are more widely supported in web browsers.
| Version | Changes |
|---|---|
| 3.0.1 | Added the DefaultFormat, GIFEnableAnimation, GIFTransparency, PNGAlpha and PNGEnableAnimation parameters |
| 3.0 | New |
The Index section contains a list of link group IDs in the order in which the link groups will appear on the disassembly index page. The link groups themselves - with the exception of OtherCode - are defined in [Index:*:*] sections (see below); OtherCode is a special built-in link group that contains links to the index pages of secondary disassemblies defined by [OtherCode:*] sections.
To see the default Index section, run the following command:
$ skool2html.py -r Index$
| Version | Changes |
|---|---|
| 2.0.5 | New |
Each Index:*:* section defines a link group (a group of links on the disassembly home page). The section names and contents take the form:
[Index:groupID:text]
Page1ID
Page2ID
...
where:
To see the default link groups and their contents, run the following command:
$ skool2html.py -r Index:
| Version | Changes |
|---|---|
| 2.0.5 | New |
The Links section defines the link text for the various pages in the HTML disassembly (as displayed on the disassembly index page). Each line has the form:
PageID=text
where:
Recognised page IDs are:
The default link text for a page is the same as the header defined in the [PageHeaders] section, except where indicated above.
The link text for a page defined by a [MemoryMap:*], [OtherCode:*], [Page:*] or [PageContent:*] section also defaults to the page header text, but can be overridden in this section.
If the link text starts with some text in square brackets, that text alone is used as the link text, and the remaining text is displayed alongside the hyperlink. For example:
MemoryMap=[Everything] (routines, data, text and unused addresses)
This declares that the link text for the ‘Everything’ memory map page will be ‘Everything’, and ‘(routines, data, text and unused addresses)’ will be displayed alongside it.
| Version | Changes |
|---|---|
| 2.5 | Added the UnusedMap page ID |
| 2.2.5 | Added the Changelog page ID |
| 2.0.5 | New |
Each MemoryMap:* section defines the properties of a memory map page. The section names take the form:
[MemoryMap:PageID]
where PageID is the unique ID of the memory map page.
Each MemoryMap:* section contains parameters in the form:
name=value
Recognised parameters and their default values are:
To see the default memory map pages and their properties, run the following command:
$ skool2html.py -r MemoryMap
A custom memory map page can be defined by creating a MemoryMap:* section for it. By default, the page will be written to maps/PageID.html; to change this, add a line to the [Paths] section. The title, page header and link text for the custom memory map page can be defined in the [Titles], [PageHeaders] and [Links] sections.
Every memory map page is built using the HTML template whose name matches the page ID, if one exists; otherwise, the stock MemoryMap template is used.
| Version | Changes |
|---|---|
| 4.0 | Added the EntryDescriptions and LengthColumn parameters, and support for the G identifier in the EntryTypes parameter |
| 2.5 | New |
An OtherCode:* section defines a secondary disassembly that will appear under ‘Other code’ on the main disassembly home page. The section name takes the form:
[OtherCode:CodeID]
where CodeID is a unique ID for the secondary disassembly; it must be limited to the characters ‘$’, ‘#’, 0-9, A-Z and a-z. The unique ID may be used by the #R macro when referring to routines or data blocks in the secondary disassembly from another disassembly.
An OtherCode:* section may either be empty or contain a single parameter named Source in the form:
Source=fname
where fname is the path to the skool file from which to generate the secondary disassembly. If the Source parameter is not provided, its value defaults to CodeID.skool.
When a secondary disassembly named CodeID is defined, the following page and directory IDs become available for use in the [Paths], [Titles], [PageHeaders] and [Links] sections:
By default, the index page is written to CodeID/CodeID.html, and the disassembly pages are written in a directory named CodeID.
Note that the index page is a memory map page, and as such can be configured by creating a [MemoryMap:*] section (MemoryMap:CodeID-Index) for it.
| Version | Changes |
|---|---|
| 5.0 | Made the Source parameter optional |
| 2.0 | New |
A Page:* section may be used to either declare a page that already exists, or define a custom page in the HTML disassembly (in conjunction with a corresponding [PageContent:*] section). The section name takes the form:
[Page:PageID]
where PageID is a unique ID for the page. The unique ID may be used in an [Index:*:*] section to create a link to the page in the disassembly index.
A Page:* section contains parameters in the form:
name=value
Recognised parameters are:
By default, the custom page is written to a file named PageID.html in the root directory of the disassembly; to change this, add a line to the [Paths] section. The title, page header and link text for the custom page can be defined in the [Titles], [PageHeaders] and [Links] sections.
Every custom page is built using the HTML template whose name matches the page ID, if one exists; otherwise, the stock Page template is used.
Note that a Page:* section may be empty; if so, it may be omitted from the ref file.
| Version | Changes |
|---|---|
| 3.5 | The JavaScript parameter specifies the JavaScript file(s) to use |
| 2.1 | New |
A PageContent:* section contains the HTML source of the body of a custom page (optionally defined in a [Page:*] section). The section name takes the form:
[PageContent:PageID]
where PageID is the unique ID of the page.
The HTML source may contain skool macros.
| Version | Changes |
|---|---|
| 2.1 | New |
The PageHeaders section defines the header text for every page in the HTML disassembly. Each line has the form:
PageID=header
where:
Recognised page IDs are:
The default header text for a page is the same as the title defined in the [Titles] section, except where indicated above.
The header text for a page defined by a [MemoryMap:*], [OtherCode:*], [Page:*] or [PageContent:*] section also defaults to the title, but can be overridden in this section.
Note that the header of the disassembly index page (GameIndex) is not defined in this section; it is composed from the values of the TitlePrefix and TitleSuffix parameters in the [Game] section.
| Version | Changes |
|---|---|
| 4.0 | New |
The Paths section defines the locations of the files and directories in the HTML disassembly. Each line has the form:
ID=path
where:
Recognised file IDs and their default paths are:
Recognised directory IDs and their default paths are:
The CodeFiles parameter contains a standard Python format string that specifies the format of a disassembly page filename based on the address of the routine or data block. The default format string is {address}.html, which produces decimal addresses (e.g. 65280.html); to produce 4-digit, upper case hexadecimal addresses instead (e.g. FF00.html), change CodeFiles to {address:04X}.html.
| Version | Changes |
|---|---|
| 4.3 | Added the CodeFiles file ID |
| 3.1.1 | Added the FontPath directory ID |
| 2.5 | Added the UnusedMap file ID |
| 2.2.5 | Added the Changelog file ID |
| 2.1.1 | Added the CodePath directory ID |
| 2.0.5 | Added the FontImagePath directory ID |
| 2.0 | New |
Each Poke:*:* section defines an entry on the ‘Pokes’ page. The section names and contents take the form:
[Poke:anchor:title]
First paragraph.
Second paragraph.
...
where:
To ensure that an entry can be linked to by the #POKE macro, the anchor name must be limited to the characters ‘$’, ‘#’, 0-9, A-Z and a-z.
Paragraphs must be separated by blank lines, and may contain HTML markup and skool macros.
The Resources section lists files that will be copied into the disassembly build directory when skool2html.py is run. Each line has the form:
fname=destDir
where:
The files to be copied must be present in skool2html.py‘s search path in order for it to find them; to see the search path, run skool2html.py -s.
If your disassembly requires pre-built images or other resources that SkoolKit does not build, listing them in this section ensures that they will be copied into place whenever the disassembly is built.
| Version | Changes |
|---|---|
| 3.6 | New |
Each Template:* section defines a template used to build an HTML page (or part of one).
To see the contents of the default templates, run the following command:
$ skool2html.py -r Template:
For more information, see HTML templates.
| Version | Changes |
|---|---|
| 4.0 | New |
The Titles section defines the title (i.e. text used to compose the <title> element) for every page in the HTML disassembly. Each line has the form:
PageID=title
where:
Recognised page IDs and their default titles are:
The title of a page defined by a [MemoryMap:*], [OtherCode:*], [Page:*] or [PageContent:*] section defaults to the page ID, but can be overridden in this section.
| Version | Changes |
|---|---|
| 4.0 | Added the Asm-* page IDs |
| 2.5 | Added the UnusedMap page ID |
| 2.2.5 | Added the Changelog page ID |
| 2.0.5 | New |
A comment may be added to a ref file by starting a line with a semicolon. For example:
; This is a comment
If a non-comment line in a ref file section needs to start with a semicolon, it can be escaped by doubling it:
[PageContent:Custom]
<code>
;; This is not a ref file comment
</code>
The content of this section will be rendered thus:
<code>
; This is not a ref file comment
</code>
If a ref file section needs to contain a line that looks like a section header (i.e. like [SectionName]), then to prevent that line from being parsed as a section header it can be escaped by doubling the opening square bracket:
[PageContent:Custom]
<code>
[[This is not a section header]
</code>
The content of this section will be rendered thus:
<code>
[This is not a section header]
</code>
In fact, any line that starts with two opening square brackets will be rendered with the first one removed.