Ref files
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):
- add a ‘Bugs’ page on which bugs are documented
- add a ‘Trivia’ page on which interesting facts are documented
- add a ‘Pokes’ page on which useful POKEs are listed
- add a ‘Changelog’ page
- add a ‘Glossary’ page
- add a ‘Graphic Glitches’ page
- add any other kind of custom page
- change the title of the disassembly
- define the layout of the disassembly index page
- define the link text and titles for the various pages in the disassembly
- define the location of the files and directories in the disassembly
- define the colours used when creating images
A ref file must be formatted into sections separated by section names inside
square brackets, like this:
The contents of each section that may be found in a ref file are described
below.
[Bug:*:*]
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:
- anchor is the name of the HTML anchor for the entry
- title is the title of the entry
Paragraphs should be separated by blank lines.
[Changelog:*]
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.
[Colours]
The Colours section contains colour definitions that will be used when
creating images. Each line has the form:
where name is the colour name, and R,G,B is an RGB triplet.
Recognised colour names and their default RGB values are:
- BLACK: 0,0,0
- BLUE: 0,0,197
- RED: 197,0,0
- MAGENTA: 197,0,197
- GREEN: 0,198,0
- CYAN: 0,198,197
- YELLOW: 197,198,0
- WHITE: 205,198,205
- BRIGHT_BLACK: 0,0,0
- BRIGHT_BLUE: 0,0,255
- BRIGHT_RED: 255,0,0
- BRIGHT_MAGENTA: 255,0,255
- BRIGHT_GREEN: 0,255,0
- BRIGHT_CYAN: 0,255,255
- BRIGHT_YELLOW: 255,255,0
- BRIGHT_WHITE: 255,255,255
- TRANSPARENT: 0,254,0
[Config]
The Config section contains configuration parameters in the format:
Recognised parameters are:
- SkoolFile - the name of the main skool file to use if not given on the
skool2html.py command line; if not specified, the
skool file with the same base name as the ref file will be used
- GameClass - the name of the Python class to use for the game; if not
specified, the generic skoollib.Game will be used
- HtmlWriterClass - the name of the Python class to use for writing the
HTML disassembly of the game; if not specified, the generic
skoolhtml.HtmlWriter will be used
- GameDir - the root directory of the game’s HTML disassembly; if not
specified, the base name of the skool or ref file given on the
skool2html.py command line will be used
Data:* sections are used to declare arbitrary data that doesn’t belong in
any other section. The section names take the form:
where DataId is a unique ID for the data that follows. The data may be
collected by the HtmlWriter class or subclass that is being used to write
the HTML disassembly to be used wherever needed.
[Fact:*:*]
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:
- anchor is the name of the HTML anchor for the entry
- title is the title of the entry
Paragraphs should be separated by blank lines.
[Game]
The Game section contains parameters in the form:
Recognised parameter names are:
- Game - the name of the game
- GameStatusBufferIncludes - a comma-separated list of addresses of entries
that should appear on the ‘Game status buffer’ page in addition to those that
are marked with a g (see the
skool file format reference)
- Logo - the skool macro to use to create the game logo image
- TitlePrefix - the prefix to use before the name of the game in the title
of the disassembly (default: ‘The complete’)
- TitleSuffix - the suffix to use after the name of the game in the title
of the disassembly (default: ‘RAM disassembly’)
[Glossary:*]
Each Glossary:* section defines an entry on the ‘Glossary’ page. The
section names and contents take the form:
[Glossary:term]
Definition.
where term is the term being defined in the entry. The definition should be
a single paragraph.
[GraphicGlitch:*:*]
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:
- anchor is the name of the HTML anchor for the entry
- title is the title of the entry
Paragraphs should be separated by blank lines.
[Graphics]
The contents of the Graphics section, if present, are used as the HTML
source for the body of the ‘Other graphics’ page.
[Index]
The Index section contains a list of link group IDs in the order in which
the link groups should appear on the disassembly index page. The link groups
themselves are defined in [Index:*:*] sections (see below).
[Index:*:*]
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:
- groupID is the link group ID (as may be declared in the [Index]
section)
- text is the text of the link group header
- Page1ID, Page2ID etc. are the IDs of the pages that will appear in
the link group
The page IDs that may be used in an [Index:*:*] section are the same as the
file IDs that may be used in the [Paths] section.
[Info]
The Info section contains release and copyright information. Each line has
the form:
where name is one of the following:
- Copyright - the text written to the bottom line of the footer of every
page of the HTML disassembly; its intended purpose is to define a copyright
message
- Created - the text written next to the copyright message in the footer of
every page of the HTML disassembly; its intended purpose is to indicate the
software used to create the disassembly
- Release - the text written to the top line of the footer of every page of
the HTML disassembly; its intended purpose is to define a message indicating
the release name and version number
If the string $VERSION appears anywhere in the Created message, it is
replaced by the version number of SkoolKit.
[Links]
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:
where:
- ID is the ID of the page
- text is the link text
Recognised page IDs are:
- Bugs - the ‘Bugs’ page
- Changelog - the ‘Changelog’ page
- DataMap - the ‘Data’ memory map page
- Facts - the ‘Trivia’ page
- GameStatusBuffer - the ‘Game status buffer’ page
- Glossary - the ‘Glossary’ page
- GraphicGlitches - the ‘Graphic glitches’ page
- Graphics - the ‘Other graphics’ page
- MemoryMap - the ‘Everything’ memory map page (default: ‘Everything’)
- MessagesMap - the ‘Messages’ memory map page
- Pokes - the ‘Pokes’ page
- RoutinesMap - the ‘Routines’ memory map page
The default link text for a page is the same as the page title (see
[Titles]) except where indicated above.
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.
[MapDetails]
The MapDetails section defines the text (if any) that appears at the top of
the memory map pages. Each line has the form:
where X is one of:
- d (data memory map)
- r (routines memory map)
- t (messages memory map)
[OtherCode:*]
Each OtherCode:* section defines a secondary disassembly that will appear
under ‘Other code’ on the main disassembly home page. The section names take
the form:
where asm_id is a unique ID for the secondary disassembly. The unique ID
may be used by the #R macro when referring to routines or data
blocks in the secondary disassembly from another disassembly.
Each OtherCode:* section contains parameters in the form:
Recognised parameters are:
- Header - the header text that will appear on each routine or data block
disassembly page in the secondary disassembly
- Index - the filename of the home page of the secondary disassembly
- IndexPageId - the ID of the secondary disassembly index page (optional);
if defined, it can be used by the #LINK macro to create a hyperlink to
the page
- Link - the link text to use for the hyperlink to the secondary
disassembly index page (defaults to the value of the Title parameter)
- Path - the directory that will contain the secondary disassembly files
- Source - the skool file from which to generate the secondary
disassembly
- Title - the header text that will appear on the the secondary disassembly
index page
[Page:*]
Each Page:* section is 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 names take the form:
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.
Each Page:* section contains parameters in the form:
Recognised parameters are:
- BodyClass - the CSS class to use for the <body> element of the page
- Content - the path (directory and filename) of a page that already exists
- JavaScript - 1 if a link to the JavaScript file (defined by the
JavaScript parameter in the [Paths] section) should be inserted into
the page, 0 otherwise (default: 0)
- Link - the link text for the page (defaults to the title)
- PageContent - the HTML source of the body of the page (may be used
instead of a [PageContent:*] section if the source can be written on a
single line)
- Path - the path (directory and filename) where the custom page will be
created
- Title - the title of the page (defaults to the page ID)
[PageContent:*]
Each PageContent:* section contains the HTML source of the body of a custom
page defined in a [Page:*] section. The section names take the form:
where PageId is the unique ID of the page (as previously declared in the
name of the corresponding [Page:*] section).
[Paths]
The Paths section defines the locations of the various files and
directories in the HTML disassembly. Each line has the form:
where:
- ID is the ID of the file or directory
- path is the path of the file or directory relative to the root directory
of the disassembly
Recognised file IDs and their default paths are:
- Bugs - the ‘Bugs’ page (default: reference/bugs.html)
- Changelog - the ‘Changelog’ page (default: reference/changelog.html)
- DataMap - the ‘Data’ memory map page (default: maps/data.html)
- Facts - the ‘Trivia’ page (default: reference/facts.html)
- GameIndex - the disassembly home page (default: index.html)
- GameStatusBuffer - the ‘Game status buffer’ page (default:
buffers/gbuffer.html)
- Glossary - the ‘Glossary’ page (default: reference/glossary.html)
- GraphicGlitches - the ‘Graphic glitches’ page (default:
graphics/glitches.html)
- Graphics - the ‘Other graphics’ page (default: graphics/graphics.html)
- JavaScript - the base name of the JavaScript file to use (default: None)
- Logo - the game logo image (default: images/logo.png)
- MemoryMap - the ‘Everything’ memory map page (default: maps/all.html)
- MessagesMap - the ‘Messages’ memory map page (default:
maps/messages.html)
- Pokes - the ‘Pokes’ page (default: reference/pokes.html)
- RoutinesMap - the ‘Routines’ memory map page (default:
maps/routines.html)
- StyleSheet - the base name of the CSS file to use (default: style.css)
Recognised directory IDs and their default paths are:
- CodePath - the directory in which the disassembly files will be written
(default: asm)
- FontImagePath - the directory in which font images (created by the
#FONT macro) will be placed (default: images/font)
- JavaScriptPath - the directory in which to store the JavaScript file
(default: .)
- ScreenshotImagePath - the directory in which screenshot images (created
by the #SCR macro) will be placed (default: images/scr)
- StyleSheetPath - the directory in which to store the CSS file (default:
.)
- UDGImagePath - the directory in which UDG images (created by the
#UDG or #UDGARRAY macro) will be placed
(default: images/udgs)
The JavaScript and CSS files (whose base names are defined by the
JavaScript and StyleSheet parameters) will be searched for by name in
the directory that contains the skool or ref file being processed, the
current working directory, and the resources subdirectory of the current
working directory (if it exists); the files are copied to the directories
defined by the JavaScriptPath and StyleSheetPath parameters.
[Poke:*:*]
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:
- anchor is the name of the HTML anchor for the entry
- title is the title of the entry
Paragraphs should be separated by blank lines.
[Titles]
The Titles section defines the titles of the various pages in the HTML
disassembly. Each line has the form:
where:
- ID is the ID of the page
- title is the page title
Recognised page IDs and their default titles are:
- Bugs - the ‘Bugs’ page (default: ‘Bugs’)
- Changelog - the ‘Changelog’ page (default: ‘Changelog’)
- DataMap - the ‘Data’ memory map page (default: ‘Data’)
- Facts - the ‘Trivia’ page (default: ‘Trivia’)
- GameIndex - the disassembly index page (default: ‘Index’)
- GameStatusBuffer - the ‘Game status buffer’ page (default: ‘Game status
buffer’)
- Glossary - the ‘Glossary’ page (default: ‘Glossary’)
- GraphicGlitches - the ‘Graphic glitches’ page (default: ‘Graphic
glitches’)
- Graphics - the ‘Other graphics’ page (default: ‘Graphics’)
- MemoryMap - the ‘Everything’ memory map page (default: ‘Memory map’)
- MessagesMap - the ‘Messages’ memory map page (default: ‘Messages’)
- Pokes - the ‘Pokes’ page (default: ‘Pokes’)
- RoutinesMap - the ‘Routines’ memory map page (default: ‘Routines’)