From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Sun, 23 May 2021 01:06:09 +0000 (+0100)
Subject: docs: wip document shapelibs, move from shapelib-toml
X-Git-Tag: otter-0.6.0~33
X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=58487ce8ac584231a6a5f89153747af84f19af8f;p=otter.git

docs: wip document shapelibs, move from shapelib-toml

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

diff --git a/docs/shapelibs.rst b/docs/shapelibs.rst
index 8c29a91d..fe729a37 100644
--- a/docs/shapelibs.rst
+++ b/docs/shapelibs.rst
@@ -204,7 +204,32 @@ Parameters
    from the top left in the image's own internal units.  If not
    supplied, calculated from the size.
 
- * ``scale``: [number, default=1].  Scale the image by a factor (in
+ * ``scale`` [number, default=1].  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.
+
+ * ``colorus`` [table].
+   If specified and non-empty, specifies that this group should be
+   instantiated multiple times, for different colours.
+
+   For each entry in the ``colours`` table, a separate piece is
+   generated for each item in the ``files`` list.  The keys of the
+   ``colours`` are recolouring names, and the values are sub-tables.
+
+   Every effective item name (i.e., after the prefix and suffix have
+   been added) must contain the substring ``_c`` exactly once, and
+   every item description must contain the substring ``_colour``
+   exactly once.  ``_c`` will be replaced with the value of the
+   recoluring's ``abbrev``, and ``_colour`` with the recolouring name
+   (the key of the ``colours`` table).
+
+   For libraries in bundles, a separate image file must be supplied
+   for each recolouring.  If ``SRC`` is not ``-``, it also must
+   contain ``_c`` which will be substitued with ``abbrev`` to find the
+   colour-specific image file.
+
+   For builtin libraries, the Otter build system will do the
+   recolouring automatically at build time.  Each recolouring should
+   hae a ``map`` entry which is a sub-sub-table mapping inputcolours
+   (strings in ``#rrggbb`` format) to output colours.
diff --git a/src/shapelib-toml.rs b/src/shapelib-toml.rs
index 9641625f..4380e796 100644
--- a/src/shapelib-toml.rs
+++ b/src/shapelib-toml.rs
@@ -27,21 +27,7 @@ pub struct GroupDetails {
   #[serde(default)] pub flip: bool,
   #[serde(default)] pub back: Option<Box <dyn PieceSpec>>,
   #[serde(default="num_traits::identities::One::one")] pub scale: f64,
-
-  /// If specified and non-empty, specifies that this group should be
-  /// instantiated multiple times, each time with a recolouring.
-  ///
-  /// For each entry in this table, the recolouring is applied to
-  /// every item in the [`files`](GroupDefn::files) list.
-  /// 
-  /// When recolouring is being done, every effective item name must
-  /// contain the substring `_c` exactly once, and every item
-  /// description must contain the substring `_colour` exactly once.
-  /// `_c` will be replaced with the recoluring's `abbrev`, and
-  /// `_colour` with the recolouring name (the key of the `colours`
-  /// table).
-  #[serde(default)]
-  pub colours: HashMap<String, RecolourData>,
+  #[serde(default)] pub colours: HashMap<String, RecolourData>,
 
   /// If specified, provides a template for the description.  The
   /// description previously calculated replaces `_desc` in this
@@ -77,16 +63,10 @@ pub enum OccultationMethod {
   },
 }
 
-/// An entry in the `colours` table, specifying one recolouring.
 #[derive(Debug,Deserialize)]
 pub struct RecolourData {
-  /// The replacement for `_c`.  See `colours` in [`GroupDetails`].
   pub abbrev: String,
-
-  #[cfg(doc)]
-  /// Each entry is `"from" = "to"` where both are 6-character
-  /// RGB hex strings (without the leading `#`).
-  pub map: HashMap<String, String>,
+  #[cfg(doc)] pub map: HashMap<String, String>,
 }
 
 #[doc(hidden)]