Extensions to the ipuz spec that we support

In general, we try to keep as close to the ipuz spec as possible. In some areas the spec is unclear or allows for interpretation. In other areas we want to extend it to get additional functionality. This document captures those differences.

Puzzle Types

Filippine puzzles

We tag dutch-style filippine puzzles as being a separate puzzle type through the https://libipuz.org/filippine#1 kind tag.

Style on BLOCKS

While this is often redundant to the solving of the puzzle, it’s nice stylistically. It lets us set a BLOCK to be a specific color rather than just black. It is recommended that implementations texture the block differently from a straight colored cells when this happens.

Example:

{"cell":"#", "style": {"color":"#ffff"}}

License

The license of the puzzle. We expect these to be a recognized string description of a well-known license, and not the full license text. The description should come from the SPDX License List when applicable. Otherwise, a URL is recommended for a custom or proprietary license.

Example:

  "org.gnome.libipuz:license": "CC-BY-SA-2.0"

Locale

Indicates the locale the puzzle is written for. This can be useful for filtering out the language of the puzzle for users that don’t speak the language. It should not affect the parsing of the puzzle at all. It is assumed that if a puzzle doesn’t have a language tag, it’s of the “C” Locale.

Example:

  "org.gnome.libipuz:locale": "nl_NL"

Charset List

The Charset list is a supplement for the charset variable. It’s supposed to be used to handle multi-character cell values. Ideally, the ipuz spec would accept both a long string as well as a list. Until the spec changes, we handle it as an extension

Example:

  "org.gnome.libipuz:charset": [ "A", "B", "C", ..., "P", "Q", "QU", "R", ..., "X", "Y", "Z" ]

HTML

We convert the HTML strings into something that’s appropriate for gmarkup. This is a subset of the valid html, though doesn’t include all entities. See Issue #16 for more details.

Unclear ipuz spec items

  • What does clueplacement do?

  • What does annotation do?

  • Do COL1 and ROW1 start at 0 or 1? the “first puzzle” example implies it starts at zero, but the spec has examples that imply it starts at 1