chore: clean up svg image mapping

author/topics/blocks/figures.adoc

@@ -416,24 +416,50 @@ image::logo.jpg[]
 --
 ======
 
-== Image mapping for SVG
 
-Metanorma supports SVG as one of its image formats. SVG have the ability to hyperlink parts of the
-image to other destinations, expressed as `<a href=...`.
+== SVG: re-mapping hyperlinks
 
-An SVG image can name a particular destination for a hyperlink, which the user wants to update
-to a different destination. If an image has been created independently of the current document, for example,
-it may hyperlink to some arbitrary destinations, which the user wants to point instead to anchors
-within the document they are authoring.
+// SVG embedding
 
-In order to support such mapping, Metanorma provides an `svgmap` 
-function [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.8.3].
-This involves wrapping the SVG image link in a figure block, given the role attribute `[.svgmap]`
-instead of `[figure]`. The image link is followed by an unordered list of link mappings: the new
-desired destination for the SVG hyperlink (expressed as either a cross-reference or a hyperlink),
-then semicolon, then the original SVG link destination.
+Metanorma supports the inclusion of SVG images.
 
-So in the following example:
+SVGs can include hyperlinks on parts of the image, expressed as `<a href="...">`.
+When an SVG image is created independently of the current document, the
+hyperlinks may point to arbitrary destinations.
+
+A document author may want to update these hyperlinks to point to anchors within
+the document. Metanorma supports the re-mapping of SVG
+hyperlinks to have them point to parts of a Metanorma document.
+
+The `svgmap` function supports the re-mapping of SVG
+hyperlinks [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.8.3].
+To use this, the SVG image is wrapped in a figure block with the role attribute
+`[.svgmap]` instead of `[figure]`.
+
+The syntax of `svgmap` is as follows.
+
+[source,asciidoc]
+----
+ [.svgmap]
+====
+image::{filename}.svg[] <1>
+
+* {remapped-link-1}; {original-link-1} <2> <3>
+* ...
+====
+----
+<1> `{filename}.svg` is the filename of the SVG image with hyperlinks.
+<2> `{remapped-link-1}` is the desired destination that replaces
+`{original-link-1}`, it could be a hyperlink or a cross-reference.
+<3> `{original-link-1}` is an existing hyperlink (content of the `href`) in the SVG
+image. The links are separated by a semicolon.
+
+This allows the author to easily update the hyperlinks within the SVG image to
+point to the appropriate locations in the current document.
+
+.Example of `svgmap` usage
+======
+In this block:
 
 [source,asciidoc]
 ----
@@ -447,16 +473,23 @@ image::action_schemaexpg1.svg[]
 ====
 ----
 
-we have SVG file `action_schemaexpg1.svg`, and it contains hyperlinks to three destinations
-`mn://action_schema`, `http://www.example.com`, and `3`. The block instructs Metanorma to rewrite
-those hyperlink destinations in the SVG, expressed as `<a href=...`,
- to point to the location of the references on the left side: 
+The image SVG file is `action_schemaexpg1.svg`, and it contains hyperlinks to three destinations:
 
-* `mn://action_schema` is rewritten to the location in the document of the `ref1` anchor 
-(or bibliographic reference); the optional cross-reference text, `Computer`, is inserted in the SVG
-hyperlink, replacing whatever text is already there, and can be used as a mouseover tip
-* `http://www.example.com` is rewritten to `http://www.example.org`
-* `3` is rewritten as the destination of the implicit cross-reference `<<express:action_schema:action_schema.basic>>`
+* `mn://action_schema`
+* `http://www.example.com`
+* `3`
 
+This block instructs Metanorma to rewrite those hyperlink destinations in the
+SVG, expressed as `<a href="...">`, to point to the location of the references
+on the left side:
 
+* `mn://action_schema` is rewritten to the location in the document of the
+`ref1` anchor (or bibliographic reference); the optional cross-reference text,
+`Computer`, is inserted in the SVG hyperlink, replacing whatever text is already
+there, and can be used as a mouseover tip.
 
+* `http://www.example.com` is rewritten to `http://www.example.org`.
+
+* `3` is rewritten as the destination of the implicit cross-reference
+`<<express:action_schema:action_schema.basic>>`.
+======