# 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

## Barred puzzles

We tag barred filippine puzzles as being a separate puzzle type
through the `https://libipuz.org/barred#1` **kind** tag. These are
parseable as normal crosswords, and will also contain
`https://ipuz.org/crossword#1`

## Filippine puzzles

We tag dutch-style filippine puzzles as being a separate puzzle type
through the `https://libipuz.org/filippine#1` **kind** tag. These are
parseable as normal crosswords, and will also contain
`https://ipuz.org/crossword#1`

## 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:
```json
{"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](https://spdx.org/licenses/) when applicable. Otherwise, a URL is
recommended for a custom or proprietary license.

Example:
```json
  "org.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:
```json
  "org.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:
```json
  "org.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.

## Cell coordinates

The spec refers to COL1 and ROW1 as a coordinate for a row but doesn't
explicitly indicate if it starts at 0 or 1? The [*first
crossword*](http://www.ipuz.org/example/first) example implies it
starts at zero, but the spec has examples (such as *Calcudoku*) that
imply the coordinates start at 1.
    * We interpret it as starting at 0, which is what some of the
      puzzles I've found in the wild use.
    * puzzaz interprets as 0-based as well, which is further
      indication we should use that.

## Unclear ipuz spec items

* What does clueplacement do?
* What does annotation do?
