From 375981504fda42276c8eacb3bd34d13de7936c07 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Sun, 15 May 2022 22:23:40 +0100 Subject: [PATCH] docs: Document new substitution syntax Signed-off-by: Ian Jackson --- docs/bundles.rst | 3 +++ docs/shapelibs.rst | 15 ++++++++------- 2 files changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/bundles.rst b/docs/bundles.rst index 396ceb27..4df544ce 100644 --- 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 `_ diff --git a/docs/shapelibs.rst b/docs/shapelibs.rst index d09f9e6b..8974b272 100644 --- 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). -- 2.30.2