skool2html.py

SYNOPSIS

skool2html.py [options] SKOOLFILE [REFFILE…]

DESCRIPTION

skool2html.py converts a skool file and ref files to HTML. When SKOOLFILE is ‘-‘, skool2html.py reads from standard input.

OPTIONS

-1, --asm-one-page

Write all routines and data blocks to a single page. This option is shorthand for -c Game/AsmSinglePage=1.

-a, --asm-labels

Use ASM labels (defined by @label directives).

-c, –config S/L

Add the line L to the ref file section S; this option may be used multiple times.

-C, --create-labels

Create default labels for unlabelled instructions. This option is intended for use alongside the -a option.

-d, –output-dir DIR

Specify the directory in which to write files; the default output directory is the current working directory.

-D, --decimal

Write the disassembly in decimal.

-H, --hex

Write the disassembly in hexadecimal.

-I, –ini param=value

Set the value of a configuration parameter (see CONFIGURATION), overriding any value found in skoolkit.ini. This option may be used multiple times.

-j, –join-css NAME

Concatenate CSS files into a single file with this name.

-l, --lower

Write the disassembly in lower case.

-o, --rebuild-images

Overwrite existing image files.

-p, --package-dir

Show the path to the skoolkit package directory and exit.

-P, –pages PAGES

Write only these pages (when using --write P); PAGES is a comma-separated list of page IDs.

-q, --quiet

Be quiet.

-r, –ref-sections PREFIX

Show the default ref file sections whose names start with PREFIX and exit.

-R, --ref-file

Show the entire default ref file and exit.

-s, --search-dirs

Show the locations that skool2html.py searches for resources.

-S, –search DIR

Add this directory to the resource search path; this option may be used multiple times.

--show-config

Show configuration parameter values.

-t, --time

Show timings.

-T, –theme THEME

Specify the CSS theme to use; this option may be used multiple times. See the section on THEMES below.

-u, --upper

Write the disassembly in upper case.

–var name=value

Define a variable that can be used by the @if directive and the #EVAL, #IF and #MAP macros. This option may be used multiple times.

-V, --version

Show the SkoolKit version number and exit.

-w, –write X

Write only these files, where X is one or more of:


d = Disassembly files o = Other code
i = Disassembly index P = Other pages
m = Memory maps
-W, –writer CLASS

Specify the HTML writer class to use; this option is shorthand for --config Config/HtmlWriterClass=CLASS.

FILES

skool2html.py searches the following directories for ref files, CSS files, JavaScript files, font files, and files listed in the [Resources] section of the ref file:


- The directory containing the skool file named on the command line
- The current working directory
- ./resources
- ~/.skoolkit
- $PACKAGE_DIR/resources
- Any other directories specified by the -S/--search option

where $PACKAGE_DIR is the directory in which the skoolkit package is installed (as shown by skool2html.py -p). When you need a reminder of these locations, run skool2html.py -s.

THEMES

The -T option sets the CSS theme. For example, if game.ref specifies the CSS files to use thus:


[Game]
StyleSheet=skoolkit.css;game.css

then:


skool2html.py -T dark -T wide game.skool

will use the following CSS files, if they exist, in the order listed:


skoolkit.css
skoolkit-dark.css
skoolkit-wide.css
game.css
game-dark.css
game-wide.css
dark.css
wide.css

CONFIGURATION

skool2html.py will read configuration from a file named skoolkit.ini in the current working directory or in ~/.skoolkit, if present. The recognised configuration parameters are:

AsmLabels

Use ASM labels (1), or don’t (0, the default).

AsmOnePage

Write all routines and data blocks to a single page (1), or to multiple pages (0, the default).

Base

Convert addresses and instruction operands to hexadecimal (16) or decimal (10), or leave them as they are (0, the default).

Case

Write the disassembly in lower case (1) or upper case (2), or leave it as it is (0, the default).

CreateLabels

Create default labels for unlabelled instructions (1), or don’t (0, the default).

EntryLabel

The format of the default label for the first instruction in a routine or data block (default: L{address}).

EntryPointLabel

The format of the default label for an instruction other than the first in a routine or data block (default: {main}_{index}).

JoinCss

If specified, concatenate CSS files into a single file with this name.

OutputDir

Write files in this directory (default: .).

Quiet

Be quiet (1) or verbose (0, the default).

RebuildImages

Overwrite existing image files (1), or leave them alone (0, the default).

Search

Directory to add to the resource search path. To specify two or more directories, separate them with commas.

Theme

CSS theme to use. To specify two or more themes, separate them with commas.

Time

Show timings (1), or don’t (0, the default).

EntryLabel and EntryPointLabel are standard Python format strings. EntryLabel recognises the following replacement fields:

address

The address of the routine or data block as it appears in the skool file.

location

The address of the routine or data block as an integer.

EntryPointLabel recognises the following replacement fields:

address

The address of the instruction as it appears in the skool file.

index

0 for the first unlabelled instruction in the routine or data block, 1 for the second, etc.

location

The address of the instruction as an integer.

main

The label of the first instruction in the routine or data block.

Configuration parameters must appear in a [skool2html] section. For example, to make skool2html.py use ASM labels and write the disassembly in hexadecimal by default (without having to use the -H and -a options on the command line), add the following section to skoolkit.ini:

[skool2html]
AsmLabels=1
Base=16

Configuration parameters may also be set on the command line by using the --ini option. Parameter values set this way will override any found in skoolkit.ini.

EXAMPLES

  1. Build the entire HTML disassembly for ‘game’:


    skool2html.py game.skool
  2. Build the entire HTML disassembly for ‘game’ in lower case, using hexadecimal notation, in the html directory:


    skool2html.py -d html -l -H game.skool
  3. Write only the ‘Bugs’ and ‘Pokes’ pages for ‘game’:


    skool2html.py -w P -P Bugs,Pokes game.skool