mformat 2: Document new format

This is not yet implemented.  Documenting it first will make these
next commits have some sensible context.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/docs/bundles.rst b/docs/bundles.rst
index 5570387602e1308756a8f12c2d281e307d3e5ea4..ee4e4ed5bb4cbd882ff858686b44bb3d99af6db9 100644 (file)
--- a/docs/bundles.rst
+++ b/docs/bundles.rst
@@ -172,6 +172,14 @@ follow the link to the latest published documentation for that format.
     - Status
     - Changes
 
+  * - ``2``
+    - unreleased
+    - unreleased
+    - Handling of the ``size``, ``scale`` and ``outline``
+      of library pieces overhauled.  ``size`` is now the in-game
+      size, and the SVG size is obtained from the SVG.
+      Library catalogues must be overhauled.
+
   * - ``1``
     - 0.x - `1.0.0 <https://www.chiark.greenend.org.uk/~ianmdlvl/otter/1.0.0/docs/README.html>`_
     - supported
@@ -179,6 +187,7 @@ follow the link to the latest published documentation for that format.
       Note that ``format`` may be omitted in this version.
 
 .. _bundle-compatibility-otter-footnote:
+
 [1] The earliest version of Otter that supports this format,
 and the newest version which uses it as the primary format.
 (Currently, newer versions of Otter can read files in any older format.)

diff --git a/docs/shapelibs.rst b/docs/shapelibs.rst
index c43a05c42ec4f1316ab270f2a0f3a62dc48581e8..d09f9e6bd47a8e619f92cdf631994aded5bbea40 100644 (file)
--- a/docs/shapelibs.rst
+++ b/docs/shapelibs.rst
@@ -77,7 +77,7 @@ The catalogue is a TOML file.
 The file should have a toplevel key ``format``, specifying which
 version of the Otter data formats the file was written to.
 This document describes ``format=1``.
-See `bundle compatibility`_.
+See :ref:`Bundle compatibility <bundle-compatibility>`.
 
 The catalogue's main contents is a dictionary
 ``groups``, mapping each group name to a sub-dict of parameters:
@@ -183,25 +183,36 @@ These are the entries which can appear in each ``group.GROUP``
 dictionary:
 
 Mandatory parameters
-`````````````````````
+````````````````````
 
- * ``size``:
-   The size at which the piece will show up in the game, in nominal
-   game coordinate units.
-   NB, this value can be affected by ``scale``.
-   [1- or 2-element array of numbers: width and height]
+ * ``files``: The list of pieces to define, one per line.  See `Files
+   entry`_.  [multi-line string]
 
-   For reference: the builtin library's chess
-   pieces are 9.5 units; the builtin playing cards are 9.65, 17.125.
+ * ``outline`` [dictionary]: Defines the outline of the piece,
+   which is used for drawing "haloes" around the piece,
+   indicating selection and movement.
 
- * ``outline`` [``"Circle"`` or ``"Rect"`` ]:
-   Defines the outline shape.  This is used for drawing selection
-   highlights, etc.  The size is taken from ``size``.  If ``outline``
-   is ``Circle``, ``size`` must be a 1-element array: ellipses are not
-   supported.
+ * ``outline`` [string]: Abbreviated way of specifying
+   ``outline = { shape: ... }``.
+   The shape mkust be specified, either via ``outline = "Shape"``
+   or by setting ``outline.shape``.
 
- * ``files``: The list of pieces to define, one per line.  See `Files
-   entry`_.  [multi-line string]
+ * ``outline.shape`` [``"Circle"`` or ``"Rect"`` ]:
+   If ``outline`` is ``Circle``, and the the nominal size
+   (calculated from all the other parameters)
+   has different width and height, the larger of the width and height is used
+   (ellipses are not supported).
+
+ * ``outline.size``: nominal size of the piece, used for calculating
+   the size of "haloes".  Note that this is not the szie of the
+   "haloes"; it is the (nominal) size of the piece image itself:
+   the "haloes" indicating selection etc. will be somewhat larger.
+   [1- or 2-element array of numbers: width and height;
+   default: calculated from the piece's ``size`` and ``scale`` ]
+
+ * ``outline.scale``: Adjusts the nominal size of the outline,
+   multiplying it by this factor.  Not meaningful together with
+   ``outline.size``.  [number; default ``1.0``]
 
 Important parameters
 ````````````````````
@@ -225,15 +236,28 @@ Geometry parameters
    the image's own internal units.  If not supplied, calculated from
    the size.  [2-element array]
 
- * ``orig_size``: If non-empty, the supplied image is first scaled
-   from ``orig_size`` to ``size``.  If both ``size`` and
-   ```orig_size`` are 2 elements, this can scale by different amounts
-   in x and y, distorting the image.  [array of up to 2 elements]
+ * ``size``:
+   The size at which the piece will show up in the game, in nominal
+   game coordinate units.
+   The supplied SVG will be reiszed from its internall specified
+   witdth and height, to that specified.
+   If the aspect ratio does not match the supplied image,
+   ``scale`` controls the behaviour.
+   (Specifying only one value for ``size`` means a square of that size.)
+   [1- or 2-element array of numbers: width and height]
+
+   For reference: the builtin library's chess
+   pieces are 9.5 units; the builtin playing cards are 9.65, 17.125.
+
+ * ``scale`` [string]: Specifies what to do if the SVG's own size does
+   not have the same aspect ratio as a sspecified ``size``:
+
+    - ``"fit"``: the image is placed within the specified ``size``;
+    - ``"cover"``: the image is placed around the specified ``size``;
+    - ``"stretch"``: the image is distorted to become exactly ``size``.
 
- * ``scale``.  Scale the image by a factor (in both x and y).
-   ``size`` and ``centre`` are in the image file's own internal
-   coordinate system, not the Otter scaled coordinates which result
-   from multiplying by by this scale factor.  [number]
+ * ``scale`` [number]: Specifies that the image SVG should be rescaled
+    by this amount.  This use of ``scale`` cannot be combined with ``size``.
 
 Parameters for defining faces
 `````````````````````````````