From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Sun, 23 May 2021 00:26:47 +0000 (+0100)
Subject: docs: wip document shapelibs, move from shapelib-toml
X-Git-Tag: otter-0.6.0~42
X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=26328ed2255e4ed61931543ece3eb46ca1069c70;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 c175b2ba..f99567f3 100644
--- a/docs/shapelibs.rst
+++ b/docs/shapelibs.rst
@@ -132,7 +132,7 @@ 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.
+   parameter.
 
 The values for these extra fields come just before the
 ``DWSCRIPTION``, after the other whitespace-delimited fields, in the
@@ -146,3 +146,21 @@ 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.
+
+Parameters
+----------
+
+ * ``item_prefix``, ``item_suffix`` (strings, default ``""``).
+   Prepaended and appended to ``ITEM-SPEC`` in ``files`` to
+   produce the item name.
+
+ * ``sort`` (string).
+   The sort key (used for item sorting in hands).
+
+   If neither the group parameter, nor the ``files`` extra field, are
+   specified, the item name is used as the sort key.
+
+   If both are specified, the group parameter is used as a template.
+   ``_s`` is replaced by the sort extra field from the ``files`` list
+   ``_c`` is replaced by the colour, if applicable.
+
diff --git a/src/shapelib-toml.rs b/src/shapelib-toml.rs
index 2c1ca998..8874042e 100644
--- a/src/shapelib-toml.rs
+++ b/src/shapelib-toml.rs
@@ -12,23 +12,9 @@ pub use crate::prelude::*;
 #[derive(Debug,Deserialize)]
 pub struct GroupDefn {
   pub files: FileList,
-
-  /// See the discussioin of the item name.
-  /// These two fields default to `""`.
   #[serde(default)] pub item_prefix: String,
   #[serde(default)] pub item_suffix: String,
-
-  /// The sort key (used for item sorting in hands).
-  ///
-  /// If neither the group property, nor the `files` extra field, are
-  /// specified, the item name is used.
-  ///
-  /// If both are specified, the group property is used as a template.
-  /// `_s` is replaced by the sort extra field from the `files` list
-  /// `_c` is replaced by the colour, if applicable.
   #[serde(default)] pub sort: String,
-
-  #[doc(hidden)]
   #[serde(flatten)] pub d: GroupDetails,
 }