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 c175b2ba185ab045a32a3eb9884fe252d429c31f..f99567f345629e9555217c776fee6f4072dbfb1a 100644 (file)
--- 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 2c1ca998428221d6a4935f87860363bcd1415adf..8874042edde0c3839a8e4d69922da681be34da83 100644 (file)
--- 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,
 }