Wattsi

Wattsi is a build tool for creating the HTML Standard from its source. It works in concert with other scripts.

Features

Currently:

• Number the sections
• Create Table of Contents
• Cross-reference <span> and <code> to <dfn>
• Create small TOC
• Cross-reference back (<dfn> menu)
• Strip out unused references
• Check for missing references
• Spec splitting
• Add output for <wpt> elements
• Add MDN annotations
• Add syntax-highlighting markup to <pre> contents

Wattsi syntax

For documentation on the "Wattsi language", e.g. things like data-x or w-nodev, see Syntax.md.

Building and running Wattsi with Docker

The easiest way to use Wattsi is via Docker. Once you have Docker, you can download and run a copy of Wattsi from the GitHub Container Registry using

docker run ghcr.io/whatwg/wattsi

The HTML build tools will automatically attempt to use this form if they cannot find a locally-installed copy of Wattsi.

If you're developing Wattsi, you can build and test it in Docker with the command make docker and docker run whatwg/wattsi. The latter accepts any Wattsi arguments, e.g. docker run whatwg/wattsi --version.

Building and running Wattsi manually

With the Free Pascal Compiler (fpc) installed, you should be able to run make manual to create the wattsi executable and supporting shared libraries.

The wattsi executable is at ./bin/wattsi. Tools such as html-build use $PATH to look for a local wattsi executable. In your terminal, run export PATH=$PATH:$(pwd)/bin. In the same terminal tab, you can now run tools that use the built wattsi executable.

For guidance on installing fpc, see the next section.

Installing the Free Pascal Compiler (fpc)

Wattsi is written in Free Pascal, so to build Wattsi, you'll need version 3.0.4 or later of the Free Pascal Compiler (fpc). You can get fpc by downloading a freepascal.org upstream release — but it’s recommended that you instead install fpc using a package manager.

Installing fpc on Debian and Ubuntu

On Debian and Ubuntu and any other Debian-derived systems, run apt install to install the necessary packages:

apt install fp-compiler fp-units-fcl fp-units-net libc6-dev

Installing fpc on macOS using Homebrew

On macOS, install Homebrew and the homebrew fpc 3.0.4 revision 1 (3.0.4_1) or later package. The revision 1 there is important — the initial 3.0.4 package will not work as expected on macOS Mojave (10.14) or later.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
brew install fpc

Installing fpc on macOS from a freepascal.org upstream release

If you don’t want to use homebrew but instead prefer to install a freepascal.org upstream release, you must get fpc 3.0.4a or later. The “a” there is important — the initial 3.0.4 package will not work as expected on macOS Mojave (10.14) or later.

https://sourceforge.net/projects/freepascal/files/Mac%20OS%20X/3.0.4/fpc-3.0.4a.intel-macosx.dmg/download

Installing XCode and the XCode command-line tools

On macOS, you may also need to have XCode and the latest XCode command-line tools installed.

If you already have XCode installed, you can ensure you have the latest XCode command-line tools by running the following command:

xcode-select --install