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 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.
- -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 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.skool
will 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).- 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.skool
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
Write only the ‘Bugs’ and ‘Pokes’ pages for ‘game’:
skool2html.py -w P -P Bugs,Pokes game.skool