AcroList

A Microsoft Word Add-in for managing abbreviations and acronyms in a document.

Features

• List — add / edit / remove abbreviations; persisted per-document via Office settings.
• Insert / refresh table — generates a sorted "List of Abbreviations" table inside a tagged content control. Re-running refreshes in place.
• Scan — two modes:
  • AI mode (recommended) — Gemini reads the entire document and returns a clean list of real abbreviations including mixed-case ones (RoBERTa, iOS, OAuth, gRPC, BERTology, XGBoost, …) with confident expansions. Section headings (INTRODUCTION, METHODOLOGY) and emphasis caps are automatically excluded.
  • Pattern mode (fallback) — Uses a broadened regex that catches any token with two or more consecutive uppercase letters. No API key required.
• First-use check — finds acronyms used in the text before their Full Form (ACR) definition appears.
• About — shows a short app overview, support details, developer contact icons, and the current app version.

Prerequisites

• Node.js 18+
• npm 9+
• Microsoft Word (desktop, 2016 or later — Windows or Mac — or Word on the web)

First-time setup

Clone or download this repository, then open a terminal in the project root (the folder that contains package.json and manifest.xml).

npm install
npm run gen-icons          # writes assets/icon-{16,32,64,80,128}.png from logo-taskpane.svg
npx office-addin-dev-certs install   # one-time HTTPS cert for localhost

On macOS or Linux, use the same commands in your shell from that folder (bash / zsh).

Optional: enable the AI filter

1. Go to https://aistudio.google.com/apikey and create a free Gemini API key (no credit card).
2. In Word, open the AcroList task pane → Settings tab.
3. Paste the key, pick a model (Gemini 2.5 Flash is the default), click Save, then Test connection.
4. On the Scan tab, run a scan — with a key saved, AcroList uses smarter detection and pre-fills suggested full forms.

The key is stored in browser localStorage scoped to localhost:3000 — it persists across documents but is not encrypted. Treat it like a low-trust dev credential.

Run in Word (development)

npm start

This launches the webpack dev server on https://localhost:3000, sideloads manifest.xml into Word, and opens a Word document with the Acronyms button on the Home tab. Click it to open the task pane.

To stop:

npm stop

Troubleshooting: “Add-in is no longer available” (Visual Studio message)

Word shows this when the development session is not running — for example after you closed the terminal that ran npm start, or opened an old Word window from a previous session.

Fix (do this every time before using AcroList in dev):

1. Close all Word windows.
2. In the project folder:

npm stop
npm start

3. Keep that terminal open while you use Word. The dev server must stay running on https://localhost:3000.
4. Use the Word window opened by npm start, or open Word fresh and click Acronyms on the Home tab.

If the error persists, run npm run restart (same as stop + start).

Manual sideload (optional): With npm run dev-server running in a terminal, in Word go to Insert → Add-ins → My Add-ins → Upload My Add-in and choose manifest.xml from this folder. You still need the dev server running for the add-in UI to load.

Troubleshooting: generic blue square icon (ribbon or Add-ins list)

Word shows a plain blue tile with a white square when it cannot download the PNG URLs in manifest.xml (that is Office’s developer placeholder, not the AcroList logo).

1. Run npm run gen-icons after changing any file in assets/ (logo.svg, logo-taskpane.svg, etc.).
2. Start (or restart) the dev session with npm start and leave the terminal open.
3. In a browser, confirm https://localhost:3000/assets/icon-32.png shows the blue bracket logo (accept the dev certificate if prompted).
4. Close Word, run npm run register, then npm start again so Word reloads the manifest (version 1.0.0.1+).

Build for distribution

npm run build

Outputs to dist/. To deploy, host dist/ over HTTPS and update the URLs in manifest.xml to point at your host, then sideload the updated manifest.

Project layout

manifest.xml                Office Add-in manifest (Word host)
src/taskpane/
  taskpane.html             side-panel markup
  taskpane.css              styles
  taskpane.ts               UI controller
  acronyms.ts               core logic: detect / store / table / first-use
scripts/gen-icons.js        rasterizes assets/logo-taskpane.svg → icon-*.png
assets/                     logo SVGs + icon-{16,32,64,80,128}.png for the manifest

How the document table works

The "Insert / Refresh table" button looks for a content control tagged AcroList-Table. If found, its contents are replaced with a freshly generated 2-column table. If not found, a new "List of Abbreviations" heading and tagged content control are inserted at the start of the document.

To move the table somewhere else, drag the bounding box in Word — the tag travels with it, so future refreshes happen in place.

Storage

Acronyms are saved into the document's Office settings under the key acrolist.store.v1. The data travels with the .docx file.

The version shown in the app's About tab is sourced from package.json (version). Bump that value for each release.

Known limitations

• Single-letter words like "I" and "A" are never flagged.
• The first-use check only recognizes definitions of the form Natural Language Processing (NLP) or NLP (Natural Language Processing). Other styles (footnote definitions, definition lists) are not yet detected.
• Editing an existing entry is done by removing and re-adding — inline edit is on the TODO list.

Developer Contact

For development inquiries, collaboration, or support related to this project:

• 👤 TATA I F.
• 📧 tifombang@gmail.com
• 📱 WhatsApp / Call: +237 679906588
• 𝕏 @incredible_ti
• 🐙 GitHub
• 💼 LinkedIn

Support This Project

AcroList is free and open source. If this tool helps you, you can support development with a small contribution:

• MTN Mobile Money — +237 679 906 588