10 option to let user define position of term hint (#36)

* feat: Option to let user define position of term hint (#10)

CHANGELOG.md

@@ -24,6 +24,11 @@ All notable changes to this project will be documented in this file. See [standa
 * **CONTRIBUTING.md:** Adapt to restructurings of testsuite ([27be1cf](https://github.com/about-code/glossarify-md/commit/27be1cf))
 * **CONTRIBUTING.md:** Explain expect-and-review workflow. Fix Debugging section. ([b57231b](https://github.com/about-code/glossarify-md/commit/b57231b))
 * **CONTRIBUTING.md:** Less verbose 'Debugging' section. Show debugging with arbitrary config. ([c670749](https://github.com/about-code/glossarify-md/commit/c670749))
+
+
+### Features
+
+* Option to let user define position of term hint ([#10](https://github.com/about-code/glossarify-md/issues/10)) ([0569652](https://github.com/about-code/glossarify-md/commit/0569652))
 -->
 
 ### [1.1.3](https://github.com/about-code/glossarify-md/compare/v1.1.2...v1.1.3) (2019-09-26)

CONTRIBUTING.md

@@ -128,7 +128,7 @@ If you're testing a bugfix or a new feature you need
 ```json
 {
     "baseDir": ".",
-    "outDir": "../../../output-actual/config-tailored/foo`",
+    "outDir": "../../../output-actual/config-tailored/foo",
     "linking": "relative",
     "includeFiles": ["."],
     "excludeFiles": [],

README.md

@@ -95,6 +95,8 @@ As you can see it's possible to have multiple glossary files. Multiple glossarie
 
 Glossaries can be associated with *term hints*. A term hint will be visible as an appendix to a term occurrence and can be used to indicate that a particular term and link refers to a glossary term. They can also be used to highlight which glossary a term belongs to.
 
+> **Since v2.0.0**: If you need more control about placement of a term hint, you can use `${term}` as a placeholder in term hints. For example, `☛ ${term}` adds `☛ ` in front of the term.
+
 ## Result
 
 Terms in glossaries have been augmented with anchor links.

lib/linker.js

@@ -116,7 +116,13 @@ function linkify(termDefs, txtNode, context, file) {
     let txtNode_ = linkifyRegex(term.regex, term, (linkNode) => {
         linkNode.title = term.getShortDescription();
         linkNode.url = getTermUrl(context, term, file);
-        linkNode.children[0].value += hasMultipleDefs ? "" : (term.hint || "");
+        if (!hasMultipleDefs && term.hint) {
+            if (/\$\{term\}/.test(term.hint)) {
+                linkNode.children[0].value = term.hint.replace("${term}", linkNode.children[0].value);
+            } else {
+                linkNode.children[0].value += term.hint;
+            }
+        }
         linkNode_ = linkNode;
         return linkNode;
     })()(txtNode);

test/input/config-tailored/config-glossaries/glossarify-md.conf.json

@@ -5,6 +5,10 @@
     "includeFiles": ["."],
     "excludeFiles": [],
     "glossaries": [
+        { "file": "./term-hint-prefix-glossary.md", "termHint": "☛ ${term}"},
+        { "file": "./term-hint-suffix-glossary.md", "termHint": "${term} ☚"},
+        { "file": "./term-hint-suffix-default-glossary.md", "termHint": "↴"},
+        { "file": "./term-hint-wrapped-glossary.md", "termHint": "☛ ${term} ☚"},
         { "file": "./disjunct-terms-glossary-a.md", "termHint": " (a/b)"},
         { "file": "./disjunct-terms-glossary-b.md", "termHint": " (a/b)"},
         { "file": "./shared-terms-glossary-a.md", "termHint": " (a&b)"},

test/input/config-tailored/config-glossaries/term-hint-document.md

@@ -0,0 +1,11 @@
+GIVEN a term hint '↴' without a placeholder '${term}'
+THEN the term hint '↴' is appended to term 'Term-Hint-Suffix-Default'.
+
+GIVEN a term hint '${term}☚' WITH a placeholder '${term}'
+THEN the term hint symbol '☚' is appended to term 'Term-Hint-Suffix'.
+
+GIVEN a term hint '☛${term}' WITH a placeholder '${term}'
+THEN the term hint symbol '☛' is prepended to term 'Term-Hint-Prefix'.
+
+GIVEN a term hint '☛ ${term} ☚' WITH a placeholder '${term}'
+THEN the term hint symbols '☛ ' and ' ☚' MUST wrap around term 'Term-Hint-Wrapped'.

test/input/config-tailored/config-glossaries/term-hint-prefix-glossary.md

@@ -0,0 +1,3 @@
+# Testing option 'glossaries.termHint'
+
+## Term-Hint-Prefix

test/input/config-tailored/config-glossaries/term-hint-suffix-default-glossary.md

@@ -0,0 +1,3 @@
+# Testing option 'glossaries.termHint'
+
+## Term-Hint-Suffix-Default

test/input/config-tailored/config-glossaries/term-hint-suffix-glossary.md

@@ -0,0 +1,3 @@
+# Testing option 'glossaries.termHint'
+
+## Term-Hint-Suffix

test/input/config-tailored/config-glossaries/term-hint-wrapped-glossary.md

@@ -0,0 +1,3 @@
+# Testing config option 'glossaries.termHint'
+
+## Term-Hint-Wrapped

test/output-expected/config-tailored/config-glossaries/glossarify-md.conf.json

@@ -5,6 +5,10 @@
     "includeFiles": ["."],
     "excludeFiles": [],
     "glossaries": [
+        { "file": "./term-hint-prefix-glossary.md", "termHint": "☛ ${term}"},
+        { "file": "./term-hint-suffix-glossary.md", "termHint": "${term} ☚"},
+        { "file": "./term-hint-suffix-default-glossary.md", "termHint": "↴"},
+        { "file": "./term-hint-wrapped-glossary.md", "termHint": "☛ ${term} ☚"},
         { "file": "./disjunct-terms-glossary-a.md", "termHint": " (a/b)"},
         { "file": "./disjunct-terms-glossary-b.md", "termHint": " (a/b)"},
         { "file": "./shared-terms-glossary-a.md", "termHint": " (a&b)"},

test/output-expected/config-tailored/config-glossaries/term-hint-document.md

@@ -0,0 +1,19 @@
+GIVEN a term hint '↴' without a placeholder '${term}'
+THEN the term hint '↴' is appended to term '[Term-Hint-Suffix-Default↴][1]'.
+
+GIVEN a term hint '${term}☚' WITH a placeholder '${term}'
+THEN the term hint symbol '☚' is appended to term '[Term-Hint-Suffix ☚][2]'.
+
+GIVEN a term hint '☛${term}' WITH a placeholder '${term}'
+THEN the term hint symbol '☛' is prepended to term '[☛ Term-Hint-Prefix][3]'.
+
+GIVEN a term hint '☛ ${term} ☚' WITH a placeholder '${term}'
+THEN the term hint symbols '☛ ' and ' ☚' MUST wrap around term '[☛ Term-Hint-Wrapped ☚][4]'.
+
+[1]: term-hint-suffix-default-glossary.md#term-hint-suffix-default
+
+[2]: term-hint-suffix-glossary.md#term-hint-suffix
+
+[3]: term-hint-prefix-glossary.md#term-hint-prefix
+
+[4]: term-hint-wrapped-glossary.md#term-hint-wrapped

test/output-expected/config-tailored/config-glossaries/term-hint-prefix-glossary.md

@@ -0,0 +1,3 @@
+# [Testing option 'glossaries.termHint'](#testing-option-glossariestermhint)
+
+## [Term-Hint-Prefix](#term-hint-prefix)

test/output-expected/config-tailored/config-glossaries/term-hint-suffix-default-glossary.md

@@ -0,0 +1,3 @@
+# [Testing option 'glossaries.termHint'](#testing-option-glossariestermhint)
+
+## [Term-Hint-Suffix-Default](#term-hint-suffix-default)

test/output-expected/config-tailored/config-glossaries/term-hint-suffix-glossary.md

@@ -0,0 +1,3 @@
+# [Testing option 'glossaries.termHint'](#testing-option-glossariestermhint)
+
+## [Term-Hint-Suffix](#term-hint-suffix)

test/output-expected/config-tailored/config-glossaries/term-hint-wrapped-glossary.md

@@ -0,0 +1,3 @@
+# [Testing config option 'glossaries.termHint'](#testing-config-option-glossariestermhint)
+
+## [Term-Hint-Wrapped](#term-hint-wrapped)

test/output-expected/config-tailored/config-glossaries/terms.json

@@ -223,6 +223,70 @@
     "aliases": [],
     "ignoreCase": false
   },
+  {
+    "shortDesc": "",
+    "term": "Term-Hint-Prefix",
+    "hint": "☛ ${term}",
+    "longDesc": "",
+    "anchor": "#term-hint-prefix",
+    "glossary": {
+      "file": "./term-hint-prefix-glossary.md",
+      "termHint": "☛ ${term}",
+      "basePath": "/{redacted}/input/config-tailored/config-glossaries/term-hint-prefix-glossary.md",
+      "outPath": "/{redacted}/output-actual/config-tailored/config-glossaries/term-hint-prefix-glossary.md"
+    },
+    "regex": {},
+    "aliases": [],
+    "ignoreCase": false
+  },
+  {
+    "shortDesc": "",
+    "term": "Term-Hint-Suffix",
+    "hint": "${term} ☚",
+    "longDesc": "",
+    "anchor": "#term-hint-suffix",
+    "glossary": {
+      "file": "./term-hint-suffix-glossary.md",
+      "termHint": "${term} ☚",
+      "basePath": "/{redacted}/input/config-tailored/config-glossaries/term-hint-suffix-glossary.md",
+      "outPath": "/{redacted}/output-actual/config-tailored/config-glossaries/term-hint-suffix-glossary.md"
+    },
+    "regex": {},
+    "aliases": [],
+    "ignoreCase": false
+  },
+  {
+    "shortDesc": "",
+    "term": "Term-Hint-Suffix-Default",
+    "hint": "↴",
+    "longDesc": "",
+    "anchor": "#term-hint-suffix-default",
+    "glossary": {
+      "file": "./term-hint-suffix-default-glossary.md",
+      "termHint": "↴",
+      "basePath": "/{redacted}/input/config-tailored/config-glossaries/term-hint-suffix-default-glossary.md",
+      "outPath": "/{redacted}/output-actual/config-tailored/config-glossaries/term-hint-suffix-default-glossary.md"
+    },
+    "regex": {},
+    "aliases": [],
+    "ignoreCase": false
+  },
+  {
+    "shortDesc": "",
+    "term": "Term-Hint-Wrapped",
+    "hint": "☛ ${term} ☚",
+    "longDesc": "",
+    "anchor": "#term-hint-wrapped",
+    "glossary": {
+      "file": "./term-hint-wrapped-glossary.md",
+      "termHint": "☛ ${term} ☚",
+      "basePath": "/{redacted}/input/config-tailored/config-glossaries/term-hint-wrapped-glossary.md",
+      "outPath": "/{redacted}/output-actual/config-tailored/config-glossaries/term-hint-wrapped-glossary.md"
+    },
+    "regex": {},
+    "aliases": [],
+    "ignoreCase": false
+  },
   {
     "shortDesc": "",
     "term": "Uppercase",