From c9bc0f9a017451fbfc796e0eec93ed1b9dbf009b Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Sun, 23 May 2021 01:03:07 +0100 Subject: [PATCH] docs: wip document shapelibs, move from shapelib-toml Signed-off-by: Ian Jackson --- docs/bundles.rst | 5 ++++ docs/shapelibs.rst | 61 ++++++++++++++++++++++++++++++++++++++++---- src/shapelib-toml.rs | 36 -------------------------- 3 files changed, 61 insertions(+), 41 deletions(-) diff --git a/docs/bundles.rst b/docs/bundles.rst index 4ec45dcb..5ad6526b 100644 --- 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 2dc1ca38..1d36b758 100644 --- 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 d28c3946..19180666 100644 --- 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, - - /// 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 -- 2.30.2