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
@labeldirectives).
- -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
-aoption.
- -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 inskoolkit.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.pysearches 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
THEMESbelow.
- -u, --upper
Write the disassembly in upper case.
- –var name=value
Define a variable that can be used by the
@ifdirective and the#EVAL,#IFand#MAPmacros. 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 fileso= Other codei= Disassembly indexP= Other pagesm= 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:
-S/--search optionwhere $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:
then:
skool2html.py -T dark -T wide game.skoolwill use the following CSS files, if they exist, in the order listed:
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¶
Build the entire HTML disassembly for ‘game’:
skool2html.py game.skoolBuild the entire HTML disassembly for ‘game’ in lower case, using hexadecimal notation, in the
htmldirectory:skool2html.py -d html -l -H game.skoolWrite only the ‘Bugs’ and ‘Pokes’ pages for ‘game’:
skool2html.py -w P -P Bugs,Pokes game.skool