.. _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 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 (after any that are automatically read by virtue of having the same filename prefix as the skool file, and before any others named on the :ref:`skool2html.py` command line) For information on how to create your own Python class for writing an HTML disassembly, see the documentation on :ref:`extending SkoolKit `. Note that the ``Config`` section must appear in a ref file that is read automatically by :ref:`skool2html.py` by virtue of having the same filename root as the skool file given on the command line (i.e. `game*.ref` if the skool file is `game.skool`). +---------+-------------------------------------------------------------------+ | 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}``) * ``AsmSinglePage`` - ``1`` to write the disassembly on a single page, or ``0`` to write a separate page for each routine and data block (default: ``0``) * ``Bytes`` - the format specification for the ``bytes`` attribute of instruction objects in the :ref:`t_asm` and :ref:`t_asm_single_page` templates (default: ''); if not blank, assembled instruction byte values are displayed on disassembly pages * ``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.') * ``DisassemblyTableNumCols`` - the number of columns in the disassembly table on disassembly pages (default: 5); this value is used by the :ref:`t_asm` and :ref:`t_asm_single_page` templates * ``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 * ``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 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, upper case hexadecimal addresses if the ``--hex`` option is used with :ref:`skool2html.py`, and decimal addresses otherwise: ``{address#IF({mode[base]}==16)(:04X)}``. +---------+-------------------------------------------------------------------+ | Version | Changes | +=========+===================================================================+ | 8.0 | Added the ``AsmSinglePage`` parameter | +---------+-------------------------------------------------------------------+ | 7.2 | Added the ``Bytes`` and ``DisassemblyTableNumCols`` parameters | +---------+-------------------------------------------------------------------+ | 6.0 | Every parameter (not just ``Logo``) may contain | | | :ref:`skool macros ` | +---------+-------------------------------------------------------------------+ | 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 | +---------+-------------------------------------------------------------------+ .. _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: * ``PNGAlpha`` - the default alpha value (0-255) to use for the transparent colour in a PNG image, where 0 means fully transparent, and 255 means fully opaque (default: ``255``) * ``PNGCompressionLevel`` - the compression level (0-9) to use for PNG image data, 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``) +---------+--------------------------------------------------------------+ | Version | Changes | +=========+==============================================================+ | 3.0.1 | Added the ``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 :ref:`indexGroup` sections. ``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 writing a single-page disassembly) * ``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 * ``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: '') * ``LabelColumn`` - ``1`` to display the 'Label' column if any entries have ASM labels defined, or ``0`` not to (default: ``0``) * ``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``) 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