✍️ Abbreviations First Time Long (ftl) (#530)

* use `rimraf` instead of `rm -rf`
* Adding the First Time Long (`firstTimeLong`) option to abbreviations
* Also added some additional testing for abbreviations (moved to tests folder with yaml cases)

---------

Co-authored-by: Rowan Cockett <rowanc1@gmail.com>

.changeset/silent-numbers-leave.md

@@ -0,0 +1,5 @@
+---
+'myst-transforms': minor
+---
+
+Add `firstTimeLong` option to the abbreviations transform to expand the abbreviation the first time it is encountered.

package.json

@@ -7,7 +7,7 @@
   "scripts": {
     "build": "turbo run build",
     "dev": "turbo run dev --parallel",
-    "clean": "turbo run clean --parallel && find . -name '.turbo' -type d -prune -exec rm -rf '{}' +",
+    "clean": "turbo run clean --parallel && find . -name '.turbo' -type d -prune -exec rimraf '{}' +",
     "lint": "turbo run lint",
     "lint:format": "turbo run lint:format",
     "test": "turbo run test",

packages/jats-to-myst/package.json

@@ -23,7 +23,7 @@
     "url": "git+https://github.com/executablebooks/mystmd.git"
   },
   "scripts": {
-    "clean": "rm -rf dist",
+    "clean": "rimraf dist",
     "lint": "eslint \"src/**/*.ts\" -c .eslintrc.cjs --max-warnings 1",
     "lint:format": "prettier --check src/*.ts src/**/*.ts",
     "test": "vitest run",

packages/myst-parser/package.json

@@ -28,7 +28,7 @@
     "url": "git+https://github.com/executablebooks/mystmd.git"
   },
   "scripts": {
-    "clean": "rm -rf dist",
+    "clean": "rimraf dist",
     "test": "vitest run",
     "test:watch": "vitest watch",
     "lint": "eslint \"src/**/*.ts\" -c .eslintrc.cjs",

packages/myst-spec-ext/package.json

@@ -22,7 +22,7 @@
     "url": "git+https://github.com/executablebooks/mystmd.git"
   },
   "scripts": {
-    "clean": "rm -rf dist",
+    "clean": "rimraf dist",
     "lint": "eslint \"src/**/*.ts\" -c .eslintrc.cjs --max-warnings 1",
     "lint:format": "prettier --check src/*.ts src/**/*.ts",
     "build:esm": "tsc --project ./tsconfig.json --module es2015 --outDir dist --declaration",

packages/myst-templates/package.json

@@ -25,7 +25,7 @@
     "url": "git+https://github.com/executablebooks/mystmd.git"
   },
   "scripts": {
-    "clean": "rm -rf dist",
+    "clean": "rimraf dist",
     "lint": "eslint \"src/**/*.ts\" -c .eslintrc.cjs",
     "lint:format": "prettier --check src/*.ts src/**/*.ts",
     "test": "vitest run",

packages/myst-to-html/package.json

@@ -25,7 +25,7 @@
     "url": "git+https://github.com/executablebooks/mystmd.git"
   },
   "scripts": {
-    "clean": "rm -rf dist",
+    "clean": "rimraf dist",
     "lint": "eslint \"src/**/*.ts\" -c .eslintrc.cjs --max-warnings 1",
     "lint:format": "prettier --check src/*.ts src/**/*.ts",
     "test": "vitest run",

packages/myst-to-jats/package.json

@@ -23,7 +23,7 @@
     "url": "git+https://github.com/executablebooks/mystmd.git"
   },
   "scripts": {
-    "clean": "rm -rf dist",
+    "clean": "rimraf dist",
     "lint": "eslint \"src/**/*.ts\" -c .eslintrc.cjs --max-warnings 1",
     "lint:format": "prettier --check src/*.ts src/**/*.ts",
     "test": "vitest run",

packages/myst-to-md/package.json

@@ -24,7 +24,7 @@
     "url": "git+https://github.com/executablebooks/mystmd.git"
   },
   "scripts": {
-    "clean": "rm -rf dist",
+    "clean": "rimraf dist",
     "lint": "eslint \"src/**/*.ts\" -c .eslintrc.cjs --max-warnings 1",
     "lint:format": "prettier --check src/*.ts src/**/*.ts",
     "test": "vitest run",

packages/myst-to-tex/package.json

@@ -25,7 +25,7 @@
     "url": "git+https://github.com/executablebooks/mystmd.git"
   },
   "scripts": {
-    "clean": "rm -rf dist",
+    "clean": "rimraf dist",
     "lint": "eslint \"src/**/*.ts\" -c .eslintrc.cjs --max-warnings 1",
     "lint:format": "prettier --check src/*.ts src/**/*.ts",
     "test": "vitest run",

packages/myst-to-typst/package.json

@@ -25,7 +25,7 @@
     "url": "git+https://github.com/executablebooks/mystmd.git"
   },
   "scripts": {
-    "clean": "rm -rf dist",
+    "clean": "rimraf dist",
     "lint": "eslint \"src/**/*.ts\" -c .eslintrc.cjs --max-warnings 1",
     "lint:format": "prettier --check src/*.ts src/**/*.ts",
     "test": "vitest run",

packages/myst-transforms/src/abbreviations.ts

@@ -1,5 +1,5 @@
 import type { Plugin } from 'unified';
-import type { Root, StaticPhrasingContent } from 'mdast';
+import type { Root, StaticPhrasingContent, Text } from 'mdast';
 import { toText } from 'myst-common';
 import { selectAll } from 'unist-util-select';
 import type { Abbreviation } from 'myst-spec';
@@ -8,7 +8,14 @@ import type { FindAndReplaceSchema, RegExpMatchObject } from 'mdast-util-find-an
 import { findAndReplace } from 'mdast-util-find-and-replace';
 
 type Options = {
+  /** An object of abbreviations { "TLA": "Three Letter Acronym" } */
   abbreviations?: Record<string, string>;
+  /**
+   * Expand the abbreviation the first time it is encountered,
+   *
+   * i.e. `TLA` --> `Three Letter Acronym (TLA)`
+   */
+  firstTimeLong?: boolean;
 };
 
 // We will not replace abbreviation text inside of these nodes
@@ -44,6 +51,17 @@ export function abbreviationTransform(mdast: Root, opts?: Options) {
     if (title) node.title = title;
   });
   replaceText(mdast, opts);
+
+  if (opts.firstTimeLong) {
+    const new_abbreviations = selectAll('abbreviation', mdast) as Abbreviation[];
+    const explained = new Set();
+    new_abbreviations.forEach((node) => {
+      if (explained.has(node.title)) return;
+      explained.add(node.title);
+      const short = node.children[0] as unknown as Text;
+      short.value = `${node.title} (${short.value})`;
+    });
+  }
 }
 
 export const abbreviationPlugin: Plugin<[Options], Root, Root> = (opts) => (tree) => {

packages/myst-transforms/tests/abbreviations.spec.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import type { Root } from 'mdast';
+import { abbreviationTransform, ReferenceState } from '../src';
+
+type TestFile = {
+  cases: TestCase[];
+};
+type TestCase = {
+  title: string;
+  before: Root;
+  after: Root;
+  opts?: Record<string, boolean>;
+};
+
+const fixtures = path.join('tests', 'abbreviations.yml');
+
+const testYaml = fs.readFileSync(fixtures).toString();
+const cases = (yaml.load(testYaml) as TestFile).cases;
+
+describe('abbreviate', () => {
+  test.each(cases.map((c): [string, TestCase] => [c.title, c]))(
+    '%s',
+    (_, { before, after, opts }) => {
+      abbreviationTransform(before as Root, opts);
+
+      expect(yaml.dump(before)).toEqual(yaml.dump(after));
+    },
+  );
+});

packages/myst-transforms/tests/abbreviations.yml

@@ -0,0 +1,103 @@
+cases:
+  - title: simple abbreviation replacement
+    opts:
+      abbreviations:
+        MyST: Markedly Structured Text
+    before:
+      type: root
+      children:
+        - type: blockquote
+          children:
+            - type: paragraph
+              children:
+                - type: link
+                  children:
+                    - type: text
+                      value: Link with MyST in it
+                - type: text
+                  value: This is about MyST Markdown
+    after:
+      type: root
+      children:
+        - type: blockquote
+          children:
+            - type: paragraph
+              children:
+                - type: link
+                  children:
+                    - type: text
+                      value: Link with MyST in it
+                - type: text
+                  value: 'This is about '
+                - type: abbreviation
+                  title: Markedly Structured Text
+                  children:
+                    - type: text
+                      value: MyST
+                - type: text
+                  value: ' Markdown'
+  - title: Abbreviation in heading
+    opts:
+      abbreviations:
+        MyST: Markedly Structured Text
+    before:
+      type: root
+      children:
+        - type: heading
+          depth: 1
+          children:
+            - type: text
+              value: Testing MyST
+    after:
+      type: root
+      children:
+        - type: heading
+          depth: 1
+          children:
+            - type: text
+              value: 'Testing '
+            - type: abbreviation
+              title: Markedly Structured Text
+              children:
+                - type: text
+                  value: MyST
+  - title: Abbreviation first time long
+    opts:
+      firstTimeLong: true
+      abbreviations:
+        MyST: Markedly Structured Text
+    before:
+      type: root
+      children:
+        - type: text
+          value: 'Testing MyST does it render out long? Does MyST now?'
+        - type: text
+          value: 'or maybe now: MyST?'
+    after:
+      type: root
+      children:
+        - type: text
+          value: 'Testing '
+        - type: abbreviation
+          title: Markedly Structured Text
+          children:
+            - type: text
+              value: Markedly Structured Text (MyST)
+        - type: text
+          value: ' does it render out long? Does '
+        - type: abbreviation
+          title: Markedly Structured Text
+          children:
+            - type: text
+              value: MyST
+        - type: text
+          value: ' now?'
+        - type: text
+          value: 'or maybe now: '
+        - type: abbreviation
+          title: Markedly Structured Text
+          children:
+            - type: text
+              value: MyST
+        - type: text
+          value: '?'

packages/tex-to-myst/package.json

@@ -24,7 +24,7 @@
     "url": "git+https://github.com/executablebooks/mystmd.git"
   },
   "scripts": {
-    "clean": "rm -rf dist",
+    "clean": "rimraf dist",
     "lint": "eslint \"src/**/*.ts\" -c .eslintrc.cjs --max-warnings 1",
     "lint:format": "prettier --check src/*.ts src/**/*.ts",
     "test": "vitest run",