.. _refFiles: Ref files ========= If you want to configure or augment an HTML disassembly, you will need one or more ref files. A ref file can be used to (for example): * add a 'Bugs' page on which bugs are documented * add a 'Trivia' page on which interesting facts are documented * add a 'Pokes' page on which useful POKEs are listed * add a 'Changelog' page * add a 'Glossary' page * add a 'Graphic glitches' page * add any other kind of custom page * change the title of the disassembly * define the layout of the disassembly index page * define the link text and titles for the various pages in the disassembly * define the location of the files and directories in the disassembly * define the colours used when creating images A ref file must be formatted into sections separated by section names inside square brackets, like this:: [SectionName] The contents of each section that may be found in a ref file are described below. .. _ref-Colours: [Colours] --------- The ``Colours`` section contains colour definitions that will be used when creating images. Each line has the form:: name=R,G,B or:: name=#RGB where: * ``name`` is the colour name * ``R,G,B`` is a decimal RGB triplet * ``#RGB`` is a hexadecimal RGB triplet (in the usual 6-digit form, or in the short 3-digit form) Recognised colour names and their default RGB values are: * ``TRANSPARENT``: 0,254,0 (#00fe00) * ``BLACK``: 0,0,0 (#000000) * ``BLUE``: 0,0,197 (#0000c5) * ``RED``: 197,0,0 (#c50000) * ``MAGENTA``: 197,0,197 (#c500c5) * ``GREEN``: 0,198,0 (#00c600) * ``CYAN``: 0,198,197 (#00c6c5) * ``YELLOW``: 197,198,0 (#c5c600) * ``WHITE``: 205,198,205 (#cdc6cd) * ``BRIGHT_BLUE``: 0,0,255 (#0000ff) * ``BRIGHT_RED``: 255,0,0 (#ff0000) * ``BRIGHT_MAGENTA``: 255,0,255 (#ff00ff) * ``BRIGHT_GREEN``: 0,255,0 (#00ff00) * ``BRIGHT_CYAN``: 0,255,255 (#00ffff) * ``BRIGHT_YELLOW``: 255,255,0 (#ffff00) * ``BRIGHT_WHITE``: 255,255,255 (#ffffff) +---------+--------------------------------------------+ | Version | Changes | +=========+============================================+ | 3.4 | Added support for hexadecimal RGB triplets | +---------+--------------------------------------------+ | 2.0.5 | New | +---------+--------------------------------------------+ .. _ref-Config: [Config] -------- The ``Config`` section contains configuration parameters in the format:: name=value Recognised parameters are: * ``GameDir`` - the root directory of the game's HTML disassembly; if not specified, the base name of the skool or ref file given on the :ref:`skool2html.py ` command line will be used * ``HtmlWriterClass`` - the name of the Python class to use for writing the HTML disassembly of the game (default: ``skoolkit.skoolhtml.HtmlWriter``); if the class is in a module that is not in the module search path (e.g. a standalone module that is not part of an installed package), the module's location may be specified thus: ``/path/to/moduledir:module.classname`` * ``RefFiles`` - a semicolon-separated list of extra ref files to use (in addition to the one named on the :ref:`skool2html.py` command line, and any others with the same filename prefix) * ``SkoolFile`` - the name of the main skool file to use if not given on the :ref:`skool2html.py ` command line; if not specified, the skool file with the same base name as the ref file will be used .. note:: The ``SkoolFile`` parameter is deprecated since version 6.4. In SkoolKit 7.0, :ref:`skool2html.py` will require the skool file as the first positional argument. For information on how to create your own Python class for writing an HTML disassembly, see the documentation on :ref:`extending SkoolKit `. +---------+-------------------------------------------------------------------+ | Version | Changes | +=========+===================================================================+ | 5.0 | Added the ``RefFiles`` parameter | +---------+-------------------------------------------------------------------+ | 3.3.1 | Added support to the ``HtmlWriterClass`` parameter for specifying | | | a module outside the module search path | +---------+-------------------------------------------------------------------+ | 2.2.3 | Added the ``HtmlWriterClass`` parameter | +---------+-------------------------------------------------------------------+ | 2.0 | New | +---------+-------------------------------------------------------------------+ .. _ref-Game: [Game] ------ The ``Game`` section contains configuration parameters that control certain aspects of the HTML output. The parameters are in the format:: name=value Recognised parameters are: * ``AddressAnchor`` - the format of the anchors attached to instructions on disassembly pages and entries on memory map pages (default: ``{address}``) * ``AsmSinglePageTemplate`` - the name of the HTML template used to build the disassembly on a single page, as opposed to a separate page for each routine and data block (default: None); set this to 'AsmAllInOne' to use the :ref:`t_AsmAllInOne` template * ``Copyright`` - the copyright message that appears in the footer of every page (default: '') * ``Created`` - the message indicating the software used to create the disassembly that appears in the footer of every page (default: 'Created using SkoolKit #VERSION.') * ``Font`` - the base name of the font file to use (default: None); multiple font files can be declared by separating their names with semicolons * ``Game`` - the name of the game, which appears in the title of every page, and also in the header of every page (if no logo is defined); if not specified, the base name of the skool file is used * ``GameStatusBufferIncludes`` - a comma-separated list of addresses of entries to include on the 'Game status buffer' page in addition to those that are marked with a ``g`` (see the :ref:`skool file format reference `) * ``InputRegisterTableHeader`` - the text displayed in the header of input register tables on routine disassembly pages (default: 'Input') * ``JavaScript`` - the base name of the JavaScript file to include in every page (default: None); multiple JavaScript files can be declared by separating their names with semicolons * ``LinkInternalOperands`` - ``1`` to hyperlink instruction operands that refer to an address in the same entry as the instruction, or ``0`` to leave them unlinked (default: ``0``) * ``LinkOperands`` - a comma-separated list of instruction types whose operands will be hyperlinked when possible (default: ``CALL,DEFW,DJNZ,JP,JR``); add ``LD`` to the list to enable the address operands of LD instructions to be hyperlinked as well * ``Logo`` - the text/HTML that will serve as the game logo in the header of every page (typically a skool macro that creates a suitable image); if not specified, ``LogoImage`` is used * ``LogoImage`` - the path to the game logo image, which appears in the header of every page; if the specified file does not exist, the name of the game is used in place of an image * ``OutputRegisterTableHeader`` - the text displayed in the header of output register tables on routine disassembly pages (default: 'Output') * ``Release`` - the message indicating the release name and version number of the disassembly that appears in the footer of every page (default: '') * ``StyleSheet`` - the base name of the CSS file to use (default: `skoolkit.css`); multiple CSS files can be declared by separating their names with semicolons * ``TitlePrefix`` - the prefix to use before the game name or logo in the header of the main index page (default: 'The complete') * ``TitleSuffix`` - the suffix to use after the game name or logo in the header of the main index page (default: 'RAM disassembly') .. note:: The ``GameStatusBufferIncludes`` parameter is deprecated since version 6.2. Use the ``Includes`` parameter in the :ref:`memoryMap` section instead. Every parameter in this section may contain :ref:`skool macros `. The ``AddressAnchor`` parameter contains a standard Python format string that specifies the format of the anchors attached to instructions on disassembly pages and entries on memory map pages. The default format string is ``{address}``, which produces decimal addresses (e.g. ``#65280``). To produce 4-digit, lower case hexadecimal addresses instead (e.g. ``#ff00``), change ``AddressAnchor`` to ``{address:04x}``. Or to produce 4-digit, lower case hexadecimal addresses if the ``--hex`` option is used with :ref:`skool2html.py`, and decimal addresses otherwise: ``{address#IF({base}==16)(:04x)}``. Note that an address anchor that starts with an upper case letter (e.g. ``#FF00``) will be interpreted as a skool macro, and so any format string that could produce such an anchor should be avoided. +---------+-------------------------------------------------------------------+ | Version | Changes | +=========+===================================================================+ | 6.0 | Every parameter (not just ``Logo``) may contain | | | :ref:`skool macros ` | +---------+-------------------------------------------------------------------+ | 5.3 | Added the ``AsmSinglePageTemplate`` parameter | +---------+-------------------------------------------------------------------+ | 4.3 | Added the ``AddressAnchor`` parameter | +---------+-------------------------------------------------------------------+ | 4.1 | Added the ``LinkInternalOperands`` parameter | +---------+-------------------------------------------------------------------+ | 4.0 | Set default values for the ``InputRegisterTableHeader`` and | | | ``OutputRegisterTableHeader`` parameters; added the | | | ``Copyright``, ``Created`` and ``Release`` parameters (which used | | | to live in the ``[Info]`` section in SkoolKit 3) | +---------+-------------------------------------------------------------------+ | 3.7 | Added the ``JavaScript`` parameter | +---------+-------------------------------------------------------------------+ | 3.5 | Added the ``Font``, ``LogoImage`` and ``StyleSheet`` parameters | | | (all of which used to live in the :ref:`Paths` section, | | | ``LogoImage`` by the name ``Logo``) | +---------+-------------------------------------------------------------------+ | 3.4 | Added the ``LinkOperands`` parameter | +---------+-------------------------------------------------------------------+ | 3.1.2 | Added the ``InputRegisterTableHeader`` and | | | ``OutputRegisterTableHeader`` parameters | +---------+-------------------------------------------------------------------+ | 2.0.5 | Added the ``Logo`` parameter | +---------+-------------------------------------------------------------------+ | 2.0.3 | Added the ``GameStatusBufferIncludes`` parameter | +---------+-------------------------------------------------------------------+ .. _ref-ImageWriter: [ImageWriter] ------------- The ``ImageWriter`` section contains configuration parameters that control SkoolKit's image creation library. The parameters are in the format:: name=value Recognised parameters are: * ``DefaultAnimationFormat`` - the default format for animated images: ``gif`` (the default) or ``png`` * ``DefaultFormat`` - the default image format: ``png`` (the default) or ``gif`` * ``GIFEnableAnimation`` - ``1`` to create animated GIFs for images that contain flashing cells, or ``0`` to create plain (unanimated) GIFs for such images (default: ``1``) * ``GIFTransparency`` - ``1`` to make the ``TRANSPARENT`` colour (see :ref:`ref-Colours`) in GIF images transparent, or ``0`` to make it opaque (default: ``0``) * ``PNGAlpha`` - the alpha value to use for the ``TRANSPARENT`` colour (see :ref:`ref-Colours`) in PNG images; valid values are in the range 0-255, where 0 means fully transparent, and 255 means fully opaque (default: ``255``) * ``PNGCompressionLevel`` - the compression level to use for PNG image data; valid values are in the range 0-9, where 0 means no compression, 1 is the lowest compression level, and 9 is the highest (default: ``9``) * ``PNGEnableAnimation`` - ``1`` to create animated PNGs (in APNG format) for images that contain flashing cells, or ``0`` to create plain (unanimated) PNG files for such images (default: ``1``) The image-creating skool macros will create a file in the default image format if the filename is unspecified, or its suffix is omitted, or its suffix is neither ``.png`` nor ``.gif``. For example, if ``DefaultFormat`` is ``png``, then:: #FONT32768,26 will create an image file named ``font.png``. To create a GIF instead (regardless of the default image format):: #FONT32768,26(font.gif) For images that contain flashing cells, animated GIFs are recommended over animated PNGs in APNG format, because they are more widely supported in web browsers. +---------+--------------------------------------------------------------+ | Version | Changes | +=========+==============================================================+ | 6.0 | ``DefaultAnimationFormat`` defaults to ``gif`` | +---------+--------------------------------------------------------------+ | 5.1 | Added the ``DefaultAnimationFormat`` parameter | +---------+--------------------------------------------------------------+ | 3.0.1 | Added the ``DefaultFormat``, ``GIFEnableAnimation``, | | | ``GIFTransparency``, ``PNGAlpha`` and ``PNGEnableAnimation`` | | | parameters | +---------+--------------------------------------------------------------+ | 3.0 | New | +---------+--------------------------------------------------------------+ .. _index: [Index] ------- The ``Index`` section contains a list of link group IDs in the order in which the link groups will appear on the disassembly index page. The link groups themselves - with the exception of ``OtherCode`` - are defined in ``[Index:*:*]`` sections (see below); ``OtherCode`` is a special built-in link group that contains links to the index pages of secondary disassemblies defined by :ref:`otherCode` sections. To see the default ``Index`` section, run the following command:: $ skool2html.py -r Index$ +---------+---------+ | Version | Changes | +=========+=========+ | 2.0.5 | New | +---------+---------+ .. _indexGroup: [Index:\*:\*] ------------- Each ``Index:*:*`` section defines a link group (a group of links on the disassembly home page). The section names and contents take the form:: [Index:groupID:text] Page1ID Page2ID ... where: * ``groupID`` is the link group ID (as may be declared in the :ref:`index` section) * ``text`` is the text of the link group header * ``Page1ID``, ``Page2ID`` etc. are the IDs of the pages that will appear in the link group To see the default link groups and their contents, run the following command:: $ skool2html.py -r Index: +---------+---------+ | Version | Changes | +=========+=========+ | 2.0.5 | New | +---------+---------+ .. _links: [Links] ------- The ``Links`` section defines the link text for the various pages in the HTML disassembly (as displayed on the disassembly index page). Each line has the form:: PageID=text where: * ``PageID`` is the ID of the page * ``text`` is the link text Recognised page IDs are: * ``AsmSinglePage`` - the disassembly page (when a single-page template is specified by the ``AsmSinglePageTemplate`` parameter in the :ref:`ref-Game` section) * ``Bugs`` - the 'Bugs' page * ``Changelog`` - the 'Changelog' page * ``DataMap`` - the 'Data' memory map page * ``Facts`` - the 'Trivia' page * ``GameStatusBuffer`` - the 'Game status buffer' page * ``Glossary`` - the 'Glossary' page * ``GraphicGlitches`` - the 'Graphic glitches' page * ``MemoryMap`` - the 'Everything' memory map page (default: 'Everything') * ``MessagesMap`` - the 'Messages' memory map page * ``Pokes`` - the 'Pokes' page * ``RoutinesMap`` - the 'Routines' memory map page * ``UnusedMap`` - the 'Unused addresses' memory map page The default link text for a page is the same as the header defined in the :ref:`pageHeaders` section, except where indicated above. The link text for a page defined by a :ref:`memoryMap`, :ref:`otherCode` or :ref:`page` section also defaults to the page header text, but can be overridden in this section. If the link text starts with some text in square brackets, that text alone is used as the link text, and the remaining text is displayed alongside the hyperlink. For example:: MemoryMap=[Everything] (routines, data, text and unused addresses) This declares that the link text for the 'Everything' memory map page will be 'Everything', and '(routines, data, text and unused addresses)' will be displayed alongside it. +---------+-------------------------------------+ | Version | Changes | +=========+=====================================+ | 5.3 | Added the ``AsmSinglePage`` page ID | +---------+-------------------------------------+ | 2.5 | Added the ``UnusedMap`` page ID | +---------+-------------------------------------+ | 2.2.5 | Added the ``Changelog`` page ID | +---------+-------------------------------------+ | 2.0.5 | New | +---------+-------------------------------------+ .. _memoryMap: [MemoryMap:\*] -------------- Each ``MemoryMap:*`` section defines the properties of a memory map page. The section names take the form:: [MemoryMap:PageID] where ``PageID`` is the unique ID of the memory map page. Each ``MemoryMap:*`` section contains parameters in the form:: name=value Recognised parameters and their default values are: * ``EntryDescriptions`` - ``1`` to display entry descriptions, or ``0`` not to (default: ``0``) * ``EntryTypes`` - the types of entries to show in the map (by default, every type is shown); entry types are identified as follows: * ``b`` - DEFB blocks * ``c`` - routines * ``g`` - game status buffer entries * ``G`` - entries whose address appears in the ``GameStatusBufferIncludes`` parameter in the :ref:`ref-Game` section * ``s`` - blocks containing bytes that are all the same value * ``t`` - messages * ``u`` - unused addresses * ``w`` - DEFW blocks * ``Includes`` - a comma-separated list of addresses of entries to include on the memory map page in addition to those specified by the ``EntryTypes`` parameter * ``Intro`` - the text (which may contain HTML markup) displayed at the top of the memory map page (default: '') * ``LengthColumn`` - ``1`` to display the 'Length' column, or ``0`` not to (default: ``0``) * ``PageByteColumns`` - ``1`` to display 'Page' and 'Byte' columns, or ``0`` not to (default: ``0``) * ``Write`` - ``1`` to write the memory map page, or ``0`` not to (default: ``1``) .. note:: The ``G`` identifier in the ``EntryTypes`` parameter (along with the ``GameStatusBufferIncludes`` parameter in the :ref:`ref-Game` section) is deprecated since version 6.2. Use the ``Includes`` parameter instead. Every parameter in this section may contain :ref:`skool macros `. To see the default memory map pages and their properties, run the following command:: $ skool2html.py -r MemoryMap A custom memory map page can be defined by creating a ``MemoryMap:*`` section for it. By default, the page will be written to `maps/PageID.html`; to change this, add a line to the :ref:`paths` section. The title, page header and link text for the custom memory map page can be defined in the :ref:`titles`, :ref:`pageHeaders` and :ref:`links` sections. Every memory map page is built using the :ref:`HTML template