Add support for ezglossary

Author: badlop

Makefile

@@ -252,6 +252,8 @@ $(MODULES): $(TMODULES)
 	sed -i 's/^\*\\\[\([[:print:]]*\)\\\]\*/`[\1]`/g' $(TMODULES)
 	sed -i 's/\([^\*]\)\*\([[:alnum:]][[:alnum:][:blank:]:|\|\.-]*\)\*$$/\1`\2`/g' $(TMODULES)
 	sed -i 's/OPTIONNAME\([\\_[:alnum:]]*\)OPTIONNAME: /**\1**: /g' $(TMODULES)
+	# Fix links to glossary defitions:
+	sed -i 's|\((def:[[:print:]]*)\)|[]\1|g' $(TMODULES)
 	# Remove unneeded escape characters \ in verbatim text:
 	sed -i 's/`\([[:print:]]*\)\\\([[:print:]]*\)`/`\1\2`/g' $(TMODULES)
 	sed -i 's/`\([[:print:]]*\)\\\([[:print:]]*\)`/`\1\2`/g' $(TMODULES)

README.md

@@ -103,6 +103,7 @@ _`bookmarks_to_pep`_ API
 _`default_db`_
 _`basic.md#captcha|CAPTCHA`_
 https://xmpp.org/extensions/xep-0045.html[XEP-0045]
+(def:c2s)
 ```
 
 gets converted into this markdown:
@@ -113,6 +114,45 @@ gets converted into this markdown:
 [default_db](toplevel.md#default_db)
 [CAPTCHA](basic.md#captcha)
 [XEP-0045](https://xmpp.org/extensions/xep-0045.html)
+[](def:c2s)
 ```
 
 There are example usage of those shorthands in ejabberd, for example in `mod_muc.erl`.
+
+## Glossary
+
+### Directly in markdown file
+
+To define a new term, write in markdown:
+
+``` markdown
+def:c2s
+: Client to Server connection in XMPP.
+```
+
+To link to that term, write in markdown:
+
+``` markdown
+Most connections in XMPP are [](def:c2s).
+```
+
+Glossary terms can be defined as singular nouns (`connection`, `port`), and later you can link to that term in plural noun (`connections`, `ports`).
+
+### In ejabberd source code
+
+Term definition is done as expected; example usage:
+``` erlang
+mod_doc() ->
+    #{desc =>
+          [?T("def:ad-hoc command"), "",
+           ?T(": Command that can be executed by an XMPP client using XEP-0050."), "",
+           ?T("This module implements XEP-0050.")]
+```
+
+In order to link to a term definition, please write simply `(def:c2s)` because `[]` becomes escaped and wouldn't work. Later `make extract` will add the `[]` automatically. Example usage:
+```erl
+mod_doc() ->
+    #{desc =>
+          ?T("This module implements some (def:ad-hoc commands) for adminitration.")
+```
+

content/assets/css/ezglossary.css

@@ -0,0 +1,28 @@
+:root {
+  --md-admonition-icon--glossary-definition: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18 2a2 2 0 0 1 2 2v16a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2zm0 2h-5v8l-2.5-2.25L8 12V4H6v16h12z"/></svg>');
+  --md-admonition-glossary-fg-color: rgb(0, 184, 212);
+}
+
+.md-typeset .admonition.glossary-definition,
+.md-typeset details.glossary-definition {
+  border-color: var(--md-admonition-glossary-fg-color);
+}
+.md-typeset .glossary-definition > .admonition-title,
+.md-typeset .glossary-definition > summary {
+  background-color: rgba(0, 184, 212, 0.1);
+}
+.md-typeset .glossary-definition > .admonition-title::before,
+.md-typeset .glossary-definition > summary::before {
+  background-color: var(--md-admonition-glossary-fg-color);
+  -webkit-mask-image: var(--md-admonition-icon--glossary-definition);
+          mask-image: var(--md-admonition-icon--glossary-definition);
+}
+
+a.mkdocs-ezglossary-link {
+  text-decoration-color: var(--md-admonition-glossary-fg-color);
+  text-decoration-line: underline;
+  text-decoration-style: wavy;
+  text-decoration-thickness: 5%;
+  text-underline-offset: 15%;
+}
+

mkdocs.yml

@@ -64,6 +64,7 @@ extra_css:
   - "assets/css/notes.css"
   - "assets/css/status.css"
   - "assets/css/headers-underline.css"
+  - "assets/css/ezglossary.css"
 
 #.
 #' markdown and hooks
@@ -93,16 +94,28 @@ markdown_extensions:
   - pymdownx.emoji:
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
       emoji_index: !!python/name:material.extensions.emoji.twemoji
+  - def_list
+  - pymdownx.tasklist:
+      custom_checkbox: true
 
 hooks:
-  - add_old_ids.py
+  #  - add_old_ids.py
   - shortcodes.py
 
 #.
 #' plugins
 #
 
 plugins:
+  - ezglossary:
+      ignore_case: true
+      inline_refs: list
+        #list_definitions: false
+        #list_references: false
+      markdown_links: true
+      plurals: en
+      templates: templates
+      tooltip: short
   #- git-committers:
   #    repository: processone/mkdocs
   #    branch: main
@@ -203,6 +216,7 @@ nav:
     - Use Cases: use-cases/index.md
     - License: COPYING.md
     - Security: SECURITY.md
+    - Glossary: glossary.md
     - Quickstart: README-GIT.md
   - Install:
     - admin/install/index.md

requirements.txt

@@ -1,4 +1,5 @@
 mkdocs
+mkdocs-ezglossary-plugin
 mkdocs-htmlproofer-plugin
 mkdocs-material
 mkdocs-redirects

templates/definition.html

@@ -0,0 +1,4 @@
+<div class="admonition glossary-definition" id="{{ target }}">
+    <p class="admonition-title">{{ term }}</p>
+    <p>{{ definition|safe }}</p>
+</div>

templates/summary.html

@@ -0,0 +1,12 @@
+<ul>
+    {% for term in terms %}
+        {% for type in types %}
+            {% for entry in glossary.get(section, term, type) %}
+                {% if type[:-1] == "def" %}
+                    <li><a href="{{ root }}{{ entry.page.url }}#{{ entry.target }}">{{term}}</a></li>
+                {% endif %}
+            {% endfor %}
+        {% endfor %}
+    {% endfor %}
+</ul>
+