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.

-O, --rebuild-audio

Overwrite existing audio 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).

RebuildAudio:

Overwrite existing audio files (1), or leave them alone (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