Implement tooltips for tag shortcode (#775)

Author: Simran-B

README.md

@@ -367,8 +367,11 @@ Inner shortcode
 Tags let you display badges, usually below a headline.
 
 This is mainly used for pointing out if a feature is only available in the
-Enterprise Edition of ArangoDB, the ArangoGraph Insights Platform, or both.
-See [Edition remarks](#edition-remarks) for details.
+ArangoDB Platform, the ArangoGraph Insights Platform, or both.
+See [Environment remarks](#environment-remarks) for details.
+
+It is also used for [Edition remarks](#edition-remarks) in content before
+version 3.12.5.
 
 #### Tabs
 
@@ -668,57 +671,55 @@ extended by a new (sub-)option in a `x.x.0` release.
 While version remarks are mostly `Introduced in: ...`, you can also mark
 deprecated features in the same manner with `Deprecated in: ...`.
 
-### Edition Remarks
+### Environment remarks
+
+Pages and sections about features that are only available in certain environments
+such as the ArangoDB Platform, the ArangoGraph Insight Platform, or the
+ArangoDB Shell should indicate where they are available using the `tag` shortcode.
 
-Pages and sections about Enterprise Edition features should indicate that the
-Enterprise Edition is required using a hint box. Use the following include in
-the general case:
+In the unified Platform and ArangoGraph but not in the Core:
 
 ```markdown
-{{< tag "ArangoDB Enterprise Edition" "ArangoGraph" >}}
+{{< tag "ArangoDB Platform" "ArangoGraph" >}}
 ```
 
-This shortcode should be placed immediately after a headline, before any version
-remarks (`<small>Introduced in: ...</small>`).
-
-To tag options in lists, place the shortcode as follows:
+In the unified Platform only:
 
 ```markdown
-- **optionName** (data type):
-
- {{< tag "ArangoDB Enterprise Edition" "ArangoGraph" >}}
-
- Version remarks and description of the option
+{{< tag "ArangoDB Platform" >}}
 ```
 
-Most Enterprise Edition features are also available in ArangoGraph, but some
-features are not or in a different form (e.g. Hot Backup). If a feature
-is not available in ArangoGraph, use the following include instead:
+In ArangoGraph only:
 
 ```markdown
-{{< tag "ArangoDB Enterprise Enterprise" >}}
+{{< tag "ArangoGraph" >}}
 ```
 
-In the release notes, add the following at the end of a section about a new
-Enterprise Edition feature:
+In the ArangoDB Shell but not the server-side JavaScript API:
 
 ```markdown
-This feature is only available in the Enterprise Edition.
+{{< tag "arangosh" >}}
 ```
 
-HTTP API options, that is options described in an `` ```openapi `` code block,
-should have a remark as follows if they are only available in the Enterprise Edition:
+This shortcode should be placed immediately after a headline, before any version
+remarks (`<small>Introduced in: ...</small>`).
 
-```markdown
-- `enterpriseOption` (boolean, _optional_): ...
- (Enterprise Edition only).
-```
+You can define a tooltip for each tag in the
+[`tag.html` template](site/themes/arangodb-docs-theme/layouts/shortcodes/tag.html).
 
-If there are both a version remark and an Enterprise Edition remark, use:
+### Edition remarks
+
+From version 3.12.5 onward, all features formerly exclusive to the
+Enterprise Edition are also included in the Community Edition.
+Therefore, using tags and other kinds of remarks to indicate what features
+require the Enterprise Edition should not be necessary.
+
+In the content **before version 3.12.5**, pages and sections about
+Enterprise Edition features should indicate that the Enterprise Edition is
+required using a tag. Use the following include in the general case:
 
 ```markdown
-- `enterpriseOption` (boolean, _optional_): ...
- (introduced in v3.11.5 and v3.12.2, Enterprise Edition only).
+{{< tag "ArangoDB Enterprise Edition" "ArangoGraph" >}}
 ```
 
 ### Add lead paragraphs

site/themes/arangodb-docs-theme/layouts/shortcodes/tag.html

@@ -1,5 +1,10 @@
+{{ $tooltips := dict
+ "ArangoGraph" "This feature is available in the ArangoGraph Insights Platform"
+ "ArangoDB Platform" "This feature is available in the unified ArangoDB Platform"
+ "arangosh" "This feature is available in the ArangoDB Shell"
+-}}
 <p class="labels">
- {{ range $.Params }}
-  <span class="label">{{ . }}</span>
- {{ end }}
+{{ range $.Params }}
+ <span class="label"{{ with index $tooltips . }} title="{{ . }}"{{ end }}>{{ . }}</span>
+{{ end }}
 </p>