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 65b56d036e756da9772ba8728e80a38202e2a479..c175b2ba185ab045a32a3eb9884fe252d429c31f 100644 (file)
--- a/docs/shapelibs.rst
+++ b/docs/shapelibs.rst
@@ -113,13 +113,15 @@ 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``.
+follows: ``library/LIB/SRC.svg`` or ``.png``.  If ``SRC`` is ``-``
+then the item name is used for ``SRC``.  (Builtin libraries: these
+support SVG only; and the ``SRC`` is not used at runtime, or when
+loading shapes --- rather, only when scraping or building.)
 
 ``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 will be HTML-escaped, so it should be plain text, not HTML.
 
 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

diff --git a/src/shapelib-toml.rs b/src/shapelib-toml.rs
index d41f98a0ff6763c54a1fc5ee65999365115e0a61..2c1ca998428221d6a4935f87860363bcd1415adf 100644 (file)
--- a/src/shapelib-toml.rs
+++ b/src/shapelib-toml.rs
@@ -148,31 +148,11 @@ pub struct RecolourData {
 #[serde(try_from="String")]
 pub struct FileList(pub Vec<FileData>);
 
-/// Contents of each line in [`files`](GroupDefn::files)
-///
-/// This is not a key value list.  The leading fields are found by
-/// splitting on whitespace, and the final field is the rest of the
-/// line.
 #[derive(Deserialize,Debug)]
 pub struct FileData {
-  /// The core of the item name.  See `GroupDefn`.
   pub item_spec: String,
-
-  /// The core of the remote file name, for pieces which are scraped.
-  ///
-  /// In bundles, is the source file name if it isn't `-`.
-  /// In builtin libs,
-  /// not used by Otter during runtime or when loading.
-  ///
-  /// When [`scraper.method`](LibraryTomlFile::scraper) is `"none"`,
-  /// this field is not used and is conventionally set to "`-`".
   pub src_file_spec: String,
-
-  /// Extra fields, normally not present.
   pub extra_fields: HashMap<String, String>,
-
-  /// Desscription.  (Shown hn the game log, for example.)
-  /// Will be HTML-escaped.
   pub desc: String,
 }