:orphan:

=============
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``
