docs: wip document shapelibs, move from shapelib-toml

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

diff --git a/docs/bundles.rst b/docs/bundles.rst
index 4ec45dcb349416e41c20abf0a561a3b64a01fc95..5ad6526b41dd97f78466cf9a7d8e440ecefcc9f4 100644 (file)
--- a/docs/bundles.rst
+++ b/docs/bundles.rst
@@ -90,3 +90,8 @@ new versions can be uploaded to the server by hand with ``otter
 upload-bundle`` and their contents will be found first.  But ``otter
 reset`` will usually be less trouble and will avoid cluttering the
 game (and the server) with previous versions.
+
+Examples
+--------
+
+xxx TODO

diff --git a/docs/shapelibs.rst b/docs/shapelibs.rst
index 2dc1ca387e8c700fea4af8c5489a5f4df8185e75..1d36b75875320141519a3d7df6465eca49cc221e 100644 (file)
--- a/docs/shapelibs.rst
+++ b/docs/shapelibs.rst
@@ -25,11 +25,6 @@ the other face to the left.  Chess pieces can be occulted, but when
 they are occulted they reveal their shape but not their colour.  The
 occulted view of a chess piece is a grey version of the piece.
 
-Pieces in shape libraries cannot have "behaviours": they can't do
-anything "special" or react to being moved or clicked on.  Pieces with
-special functionality do exist, but they are built into Otter.  (See
-_`Piece specs` for all the kinds of piece.)
-
 A library has a **library name**.  This is a string.  For a library in
 a bundle, it's the ``LIB`` part of the filename
 ``libraries/LIB.toml``.
@@ -41,3 +36,59 @@ so pieces should have the same item name (only) if they are in some
 sense equivalent.  The item name is a string but may contain only
 ASCII alphanumerics, plain ASCII spaces, and the punctuation
 characters ``-._``.
+
+Pieces in shape libraries cannot have "behaviours": they can't do
+anything "special" like react to being moved or clicked on.  Pieces
+with special functionality do exist, but they are built into Otter.
+(See _`Piece specs` for all the kinds of piece.)
+
+A library consists of a **catalogue**, and a set of **image files**
+which contain the actual appearances.  When a library is in a bundle
+the catalogue is ``libraries/LIB.toml`` and the image files are in a
+directory ``libraries/LIB.toml``.  The layout of Otter's builtin
+libraries is similar.
+
+Catalogue
+---------
+
+The catalogue defines what pieces the library contains.  For each
+piece it defines each face looks like, how big it is on the screen,
+whether and how the piece can be occulted, and what source image files
+are to be used to display it.
+
+The catalogue is a TOML file.  Its main contents is a table
+``groups``, mapping each group name to a sub-table of parameters:
+
+Each catalogue is organised into named **groups**.  Each group defines
+some pieces.  It specifies various **parameters**, and also gives a
+list of indvidual image files which should be processed according to
+those parameters.
+
+For example:
+
+::
+
+  [group.dried]
+  outline = "Circle"
+  size = [14]
+  orig_size = [64, 48]
+  centre = [32,24]
+
+  files = """
+  dried-lemon  -       a dried lemon
+  """
+
+This defines a group ``dried``, with parameters such as ``size`` and
+``outline``.  The ``files`` entry defines the list of pieces.
+
+The group names are not visible when using the library, but they can
+be used within the library using the ``inherit`` feature.
+
+The builtin catalogues also have a toplevel table ``scraper``, which
+controls how the builtin shape data is processed during the build, and
+how it is to be updated.  (Downloads are never automatically run
+during the build.  If you updated the catalougue in a way that means
+files should be re-downloaded, you should re-run ``./media-scraper
+library/LIB.toml``.)
+
+Examples

diff --git a/src/shapelib-toml.rs b/src/shapelib-toml.rs
index d28c3946c967dfefa02a1a2a241a056a857bd601..19180666672f9a1714b6d57f2b7c9509168aace0 100644 (file)
--- a/src/shapelib-toml.rs
+++ b/src/shapelib-toml.rs
@@ -2,46 +2,10 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // There is NO WARRANTY.
 
-//! This module has the documentation for the `library/*.toml`
-//! library spec files.
-//!
-//! It is in the form of Rust data structures, as will be parsed from
-//! the [TOML](https://toml.io/en/) by Rust's `serde` facility.  Each
-//! Rust `struct` corresponds to a TOML table.  A `HashMap` is also a
-//! TOML Table (ie, a `key = value` mapping).  A `Vec` is a TOML Array
-//! (ie, a list).  (There are a number of wrinkles where the parsing
-//! deviates from these conventions; these are documented explicitly.)
-//!
-//! Each `*.toml` file contains the information in
-//! [`LibraryTomlFile`], so start there.
-//!
-//! It is probably best to read this documentation in conjuncton with
-//! the provided `library/wikimedia.toml` and `library/edited.toml`,
-//! which demonstrate the use of the various features.
-
 pub use crate::prelude::*;
 
 #[doc(hidden)] pub type LLE = shapelib::LibraryLoadError;
 
-#[cfg(doc)]
-/// Each file `library/*.toml` contains this.
-///
-/// (Ignore the "Trait implementations" and everything that follows.)
-pub struct LibraryTomlFile {
-  /// A TOML table of groups.  Each group has a name, a can specify
-  /// various (inheritable) properties, and also gives a list of
-  /// indvidual SVG files which should be processed this way.
-  pub groups: HashMap<String, GroupDefn>,
-
-  /// Configuration for the scraper.
-  ///
-  /// The scraper is never automatically run during the build.  If you
-  /// updated the TOML file in a way that means files should be
-  /// re-downloaded, you should re-run `./media-scraper
-  /// library/`_lib_`.toml`
-  pub scraper: Scraper
-}
-
 /// Details for a group of pieces. See also [`GroupDetails`].
 ///
 /// This is separate from `GroupDetails` only to make the