Fixes for SynTags presentation.

WRITING_DOCS.md

@@ -350,6 +350,7 @@ Which outputs Markdown code that renders like:
 The `Function&Module` header is used to document a function which has a related module of the same name.  It should have a Description sub-block.  It is recommended to also have Usage, Arguments, and Example/Examples sub-blocks. You should have Usage blocks for both calling as a function, and calling as a module.  Usage sub-block body lines are also used in constructing the Cheat Sheet index file:
 
     // Function&Module: oval()
+    // Synopsis: Creates an Ovel shape.
     // Topics: 2D Shapes, Geometry
     // Usage: As a Module
     //   oval(rx,ry);
@@ -375,6 +376,7 @@ The `Function&Module` header is used to document a function which has a related
 Which outputs Markdown code that renders like:
 
 > ### Function&Module: oval()
+> **Synopsis:** Creates an oval shape.
 > **Topics:** 2D Shapes, Geometry
 >
 > **Usage:** As a Module
@@ -414,13 +416,15 @@ These Type blocks can have a number of sub-blocks.  Most sub-blocks are optional
 
 - `// Aliases: alternatename(), anothername()`
 - `// Status: DEPRECATED`
+- `// Synopsis: A short description.`
+- `// SynTags: VNF, Geom`
 - `// Topics: Comma, Delimited, Topic, List`
+- `// See Also: otherfunc(), othermod(), OTHERCONST`
 - `// Usage:`
 - `// Description:`
 - `// Figure:` or `// Figures`
 - `// Continues:`
 - `// Arguments:`
-- `// See Also: otherfunc(), othermod(), OTHERCONST`
 - `// Example:` or `// Examples:`
 
 
@@ -449,6 +453,41 @@ Which outputs Markdown code that renders like:
 > **Status:** DEPRECATED, use foo() instead
 
 
+Synopsis Block
+--------------
+
+The Synopsis block gives a short one-line description of the current function or module.  This is shown in various indices:
+
+    // Synopsis: A short one-line description.
+
+Which outputs Markdown code that renders like:
+
+> **Synopsis:** A short one-line description.
+
+
+SynTags Block
+-------------
+
+The SynTags block can be used with the Synopsis block, and the DefineSynTags configuration file block,
+to allow you to add hover-text tags to the end of Synopsis lines.  This is shown in various indices:
+
+In the .openscad_docsgen_rc config file:
+
+    DefineSynTags:
+      VNF = Can return an VNF when called as a function.
+      Geom = Can return geometry when called as a module.
+      Path = Can return a Path when called as a function.
+
+In scadfile documentation:
+
+    // Synopsis: Creates a weird shape.
+    // SynTags: VNF, Geom
+
+Which outputs Markdown code that renders like:
+
+> **Synopsis:** Creates a weird shape. \[<abbr title="Can return an VNF when called as a function.">VNF</abbr>\] \[<abbr title="Can return geometry when called as a module.">Geom</abbr>\]
+
+
 Topics Block
 ------------
 
@@ -461,6 +500,19 @@ Which outputs Markdown code that renders like:
 > **Topics:** 2D Shapes, Geometry, Masks
 
 
+See Also Block
+--------------
+
+The See Also block is used to give links to related functions, modules, or
+constants.  It looks like:
+
+    // See Also: relatedfunc(), similarmodule()
+
+Which outputs Markdown code that renders like:
+
+> **See Also:** [relatedfunc()](otherfile.scad#relatedfunc), [similarmodule()](otherfile.scad#similarmodule)
+
+
 Usage Block
 -----------
 
@@ -571,19 +623,6 @@ Which outputs Markdown code that renders like:
 > `dflt`         | Default value.
 
 
-See Also Block
---------------
-
-The See Also block is used to give links to related functions, modules, or
-constants.  It looks like:
-
-    // See Also: relatedfunc(), similarmodule()
-
-Which outputs Markdown code that renders like:
-
-> **See Also:** [relatedfunc()](otherfile.scad#relatedfunc), [similarmodule()](otherfile.scad#similarmodule)
-
-
 Figure Block
 --------------
 
@@ -1017,6 +1056,15 @@ To prioritize the ordering of files when generating the Table of Contents and ot
 
 ---
 
+You can define SynTags tags using the DefineSynTags block:
+
+    DefineSynTags:
+      Geom = Can return geometry when called as a module.
+      Path = Can return a Path when called as a function.
+      VNF = Can return a VNF when called as a function.
+
+---
+
 You can also use the DefineHeader block in the config file to make custom block headers:
 
     DefineHeader(Text;ItemOnly): Returns

openscad_docsgen/blocks.py

@@ -155,9 +155,8 @@ def __init__(self, title, subtitle, body, origin, parent=None):
 
     def get_file_lines(self, controller, target):
         sub = self.parse_links(self.subtitle, controller, target)
-        sub = target.escape_entities(sub)
-        out = target.block_header(self.title, sub)
-        out += target.mouseover_tags(self.parent.syntags)
+        sub = target.escape_entities(sub) + target.mouseover_tags(self.parent.syntags, htag="abbr")
+        out = target.block_header(self.title, sub, escsub=False)
         return out
 
 
@@ -698,7 +697,7 @@ def get_synopsis(self, controller, target):
         out = "{}{}{}".format(
             " – " if self.synopsis or self.syntags else "",
             target.escape_entities(sub),
-            target.mouseover_tags(self.syntags),
+            target.mouseover_tags(self.syntags, htag="abbr"),
         )
         return out
 

openscad_docsgen/target_wiki.py

@@ -58,15 +58,15 @@ def paragraph(self, lines=[]):
         lines.append("")
         return lines
 
-    def mouseover_tags(self, tags, file=None):
+    def mouseover_tags(self, tags, file=None, htag="sup"):
         if not file:
-            fmt = '&nbsp;<sup title="{1}" style="color: #077;">\[{0}\]</sup>'
+            fmt = '&nbsp;\[<{3} title="{1}">{0}</{3}>\]'
         elif '#' in file:
-            fmt = '&nbsp;<sup title="{1}">[\[{0}\]]({2})</sup>'
+            fmt = '&nbsp;\[<{3} title="{1}">[{0}]({2})</{3}>\]'
         else:
-            fmt = '&nbsp;<sup title="{1}">[\[{0}\]]({2}#{0})</sup>'
+            fmt = '&nbsp;\[<{3} title="{1}">[{0}]({2}#{0})</{3}>\]'
         out = "".join(
-            fmt.format(tag, text, file)
+            fmt.format(tag, text, file, htag)
             for tag, text in tags.items()
         )
         return out

setup.py

@@ -2,7 +2,7 @@
 
 from setuptools import setup
 
-VERSION = "2.0.37"
+VERSION = "2.0.38"
 
 
 with open('README.rst') as f: