docs: Document new substitution syntax

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/docs/bundles.rst b/docs/bundles.rst
index 396ceb27563253d97b250b5faf4c2e2c18fdb30c..4df544ce40c275ed25f0ebb00d774fe085e7a1e5 100644 (file)
--- a/docs/bundles.rst
+++ b/docs/bundles.rst
@@ -181,6 +181,9 @@ follow the link to the latest published documentation for that format.
       Library catalogues must be overhauled.
     - Handling of the ``angle`` parameter in game specs is now
       much more sensible, and also accurately documented.
+    - Shape library escaping in text strings now uses ``${subst}``
+      (while in filenames and item names, still ``__c`` since that
+      appears literally in filenames).
 
   * - ``1``
     - 0.x - `1.0.0 <https://www.chiark.greenend.org.uk/~ianmdlvl/otter/1.0.0/docs/README.html>`_

diff --git a/docs/shapelibs.rst b/docs/shapelibs.rst
index d09f9e6bd47a8e619f92cdf631994aded5bbea40..8974b272f59d5a24e61d9381a685879198ef0d7b 100644 (file)
--- a/docs/shapelibs.rst
+++ b/docs/shapelibs.rst
@@ -310,9 +310,10 @@ Other group parameters
    Every effective item name (i.e., after the ``item_prefix`` and
    ``item_suffix`` have been added) must contain the substring ``_c``
    exactly once, and every item description must contain the substring
-   ``_colour`` exactly once.  ``_c`` will be replaced with the value
-   of the recoluring's ``abbrev``, and ``_colour`` with the
-   recolouring name (the key of the ``colours`` dict).
+   ``${colour}`` exactly once.  ``_c`` in the item name will be
+   replaced with the value of the recoluring's ``abbrev``, and
+   ``${colour}`` with the recolouring name (the key of the ``colours``
+   dict).
 
    For libraries in bundles, a separate image file must be supplied
    for each recolouring.  If ``SRC`` is not ``-``, it also must
@@ -326,10 +327,10 @@ Other group parameters
 
  * ``desc`` [string: template]: : If specified, provides a template
    for the description, to allow formulaic descriptions of pieces in
-   this group.  The string specified by ``desc`` must contain ``_desc``
+   this group.  The string specified by ``desc`` must contain ``${desc}``
    exactly once; that will be replaced with the description calculated
-   according to the other rules.  (``_desc`` substitution happens
-   after ``_colour`` substitution.)
+   according to the other rules.  (``${desc}`` substitution happens
+   after ``${colour}`` substitution.)
 
  * ``occulted`` [dict, contents depend on ``occulted.method``].  If
    specified, these pieces be occulted.  For example, when a player
@@ -342,7 +343,7 @@ Other group parameters
     this piece.  The sub-entry ``occulted.colour`` names a
     recolouring - one of the keys of the ``colours`` group parameter.
     When the piece is occulted it will show that colour, instead of
-    its actual colour.  In the description, ``_colour`` will be elided
+    its actual colour.  In the description, ``${colour}`` will be elided
     rather than substituted (along with up to one of any spaces either
     side of it).