From: Ian Jackson Date: Sun, 23 May 2021 00:17:11 +0000 (+0100) Subject: docs: wip document shapelibs, move from shapelib-toml X-Git-Tag: otter-0.6.0~44 X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=0919b90b73daa92302098ec62449c18bae6589b4;p=otter.git docs: wip document shapelibs, move from shapelib-toml Signed-off-by: Ian Jackson --- diff --git a/docs/shapelibs.rst b/docs/shapelibs.rst index 1d36b758..65b56d03 100644 --- a/docs/shapelibs.rst +++ b/docs/shapelibs.rst @@ -30,12 +30,15 @@ a bundle, it's the ``LIB`` part of the filename ``libraries/LIB.toml``. Each piece in a library has an **item name**. Item names are unique -within a library. Item names do not need to be unique within a game, -but there are places where a piece is found *just* by the item name, -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 ``-._``. +within a library. The item name is used within Otter to refer to the +piece (for example, with ``otter library-add``). + +Item names do not need to be unique within a game, but there are +places where a piece is found *just* by the item name, 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 @@ -64,9 +67,7 @@ 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: - -:: +For example:: [group.dried] outline = "Circle" @@ -91,4 +92,55 @@ 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 +Files entry +----------- + +Each group has a table key ``files``. This is a string, which is +treated as a series of lines (so it is best to use the TOML multi-line +string syntax). + +Each line of which has (normally) three fields (the leading ones +terminated by whitespace). ``#`` comment lines are supported and +blank lines are ignored. + +Each non-empty non-comment line in ``files`` specifies a single piece, +like this:: + + ITEM-SPEC SRC DESCRIPTION... + +The **item name** of the piece will be ``ITEM-SPEC`` sandwiched +between the ``item_prefix`` and ``item_suffix`` parameters (see +below). + +The **image filename** is derived from ``SRC`` or the item name, as +follows: ``library/LIB/SRC.svg`` or ``.png``. (Builtin libraries +support SVG only.) If ``SRC`` is ``-`` then the item name is used for +``SRC``. + +``DESCRIPTION`` is the **description**, a string which will be used to +describe the piece (eg in in-game log messages). In English, it +should contain an article. Eg, ``the black queen``, ``a white pawn``. + +It is also possible to specify additional data for each piece by +adding fields to each line in ``files``. This is done by adding a +line at the start starting with ``:`` listing the extra fields, and +then additng one additional whitespace separated value on each data +line. Values given for unknown field are ignored. + +Currently the extra fields supported are: + + * ``sort``: Specifies the sort key. See the ``sort`` group + definition property. + +The values for these extra fields come just before the +``DWSCRIPTION``, after the other whitespace-delimited fields, in the +same order as specified in the ``:`` heading line. + +Item names +`````````` + +Item names are conventionally structured using a hierarchical name +with ``-`` between the components. Do not put ``/`` in item names use +``_`` only as a word separator within ``-``-separated parts. + +See the existing examples to see what item names usually look like. diff --git a/src/shapelib-toml.rs b/src/shapelib-toml.rs index 19180666..d41f98a0 100644 --- a/src/shapelib-toml.rs +++ b/src/shapelib-toml.rs @@ -6,52 +6,11 @@ pub use crate::prelude::*; #[doc(hidden)] pub type LLE = shapelib::LibraryLoadError; -/// Details for a group of pieces. See also [`GroupDetails`]. -/// -/// This is separate from `GroupDetails` only to make the -/// implementation convenient (for complicated reasons). At the -/// library TOML file level, there is no meaningful difference between -/// the fields in this struct, and the ones in `GroupDetails` -// // At the implementation level, each loaded item contains an // `Arc`, which is simply stored directly. The // `GroupDefn` is processed. #[derive(Debug,Deserialize)] pub struct GroupDefn { - /// `files` is a multi-line string, each line of which has - /// (normally) three fields (the leading ones terminated by - /// whitespace). The fields are those in [`FileData`]. `#` - /// comments are supported. - /// - /// Each non-empty non-comment line in `files` specifies a single - /// SVG to be made aavailable as a piece. - /// - /// The piece has am **item name** which is used within Otter to - /// refer to the piece (for example, with `otter library-add`). - /// The SVG filename is derived from the item name, as follows: - /// `library/`_lib_`/`_itemname_`.svg`. - /// - /// The `itemname` is the `item_spec` from each entry in `files` - /// (see [`FileData`] sandwiched between `item_prefix` and - /// `item_suffix` - /// - /// Item names are conventionally structured using a hierarchical - /// name with `-` between the components. Do not put `/` or `_` in - /// item names. - /// - /// It is also possible to specify additional data for each item by - /// adding fields to each line. This is done by adding a line at - /// the start starting with `:` and then additing one additional - /// whitespace separated value on each data line. Unknown - /// `fieldname` values are ignored. Currently the extra fields - /// supported are: - /// - /// * `sort`: Specifies the sort key. See the `sort` group - /// definition property. - /// - /// The values for these extra fields come just before the - /// dwscription, after the other whitespace-delimited fields, in the - /// same order as specified in the `:` heading line. pub files: FileList, /// See the discussioin of the item name.